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IMPORTANT NOTICE 


Texas Instruments (TI) reserves the right to make changes to or to discontinue 
any semiconductor product or service identified in this publication without notice. 
Tl advises its customers to obtain the latest version of the relevant information 
to verify, before placing orders, that the information being relied upon is current. 


Tl warrants performance of its semiconductor products to current specifications 
in accordance with Tl’s standard warranty. Testing and other quality control tech- 
niques are utilized to the extent Tl deems necessary to support this warranty. Un- 
less mandated by government requirements, specific testing of all parameters of 
each device is not necessarily performed. 


Tl assumes no liability for TI applications assistance, customer product design, 
software performance, or infringement of patents or services described herein. 
Nor does TI warrant or represent that license, either express or implied, is granted 
under any patent right, copyright, mask work right, or other intellectual property 
right of Tl covering or relating to any combination, machine, or process in which 
such semiconductor products or services might be or are used. 
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This document contains the following chapters: 


Introduction and Installation 

Provides an overview of the TMS320C25 development tools, describes the 
code development process, and contains instructions for installing the C 
compiler. 


Compiler Operation 

Describes the three major components of the C compiler (preprocessor, 
parser, and code generator), contains instructions for invoking individually 
each of these components or for invoking a shell program to compile and 
assemble a C source file. It also discusses linking and archiving C pro- 
grams. 


TMS320C25 C Language 
Discusses the differences between the C language supported by the 
TMS320C25 C compiler and standard Kernighan and Ritchie C. 


Runtime Environment 

Contains technical information on how the compiler uses the TMS320C25 
architecture; discusses memory and register conventions, stack organiza- 
tion, function-call conventions, and system initialization; provides informa- 
tion needed for interfacing assembly language to C programs. 


Runtime-Support Functions 

Describes the header files that are shipped with the C compiler, as well as 
the macros, functions, and types that they declare; summarizes the runtime- 
support functions according to category (header); and provides an alpha- 
betical reference of the runtime-support functions. 


Appendix A Fatal Errors 


Shows the format of compiler error messages and lists all the error mes- 
sages issued by fatal errors. 


Appendix B Preprocessor Directives 


Describes the standard preprocessor directives that the compiler supports. 
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Related Documentation 


You should obtain a copy of The C Programming Language (by Brian W. 
Kernighan and Dennis M. Ritchie, published by Prentice-Hall, Englewood 
Cliffs, New Jersey, 1978) to use with this manual. 


You may find these two books useful as well: 
La Kochan, Steve G. Programming in C, Hayden Book Company. 


La Sobelman, Gerald E. and David E. Krekelberg. Advanced C:Tech- 
niques and Applications, Que Corporation, 1985. 


The following books, which describe the TMS320C25 and related support 
tools, are available from Texas Instruments. To obtain TI literature, please 
call the Texas Instruments Customer Response Center (CRC) at 
1-800-232-3200. 


Lai The TMS320 Family-Second Generation User’s Guide (literature 
number SPRU014) discusses hardware aspects of the TMS320 family 
second-generation devices, including the TMS320C25. Topics in this 
user’s guide include pin functions, architecture, stack operation, and in- 
terfaces; the manual also includes the TMS320C2x assembly language 
instruction set. 


Lk The TMS320 Family-Second Generation Data Sheet (literature num- 
ber SPRS010) contains the recommended operating conditions, elec- 
trical specifications, and timing characteristics for the TMS32020 and 
TMS320C25. 


Ly The 7MS320C1x/TMS320C2x Assembly Language Tools User’s- 
Guide (literature number SPRU018) describes the assembly language 
tools (assembler, linker, archiver, and object format converter), assem- 
bler directives, macros, common object file format, and symbolic de- 
bugging directives. 
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Style and Symbol Conventions 


This document uses the following conventions: 


Cal 


Ld 


‘7 


In this document, program listings or examples, interactive displays, fi- 
lenames, file contents, and symbol names are shown in a special 
font. Examples may use a@bold version of the special font for em- 
phasis. Here is a sample declaration: 


extern float sine[]; /* This is the object */ 
float *sine p = sine; /*® Declare aC pointer 


EO. POLNG. LO: Le A. 
£ = sine p[4]; /* Access sine like a 
normal array mf 


In syntax descriptions, the instruction, command, or directive is in a 
bold face font and parameters are in /talics. Portions of a syntax that 
are in bold face should be entered as shown; portions of a syntax that 
are in italics describe the type of information that should be entered. 


Square brackets (| and J ) Identify optional information. if you use an 
option, you specify the information within the brackets; you don’t enter 
the brackets themselves. Here is an example of the syntax to invoke a 
program: 


dspcc input file [output file] [options] 


The dspcc program can use three inputs. The first input, input file, is 
required. The second input output file, is optional. If you don’t specify an 
output filename the program uses the input filename with a different ex- 
tension. The third input is optional and consists of a letter preceded with 
a dash, that specifies the running mode. 


Square brackets are also used as part of the pathname specification for 
VMS pathnames; in this case, the brackets are actually part of the path- 
name (they don’t represent options). 


Read This First 


os SO OT SO SS OS OS SSS OSS AR RES Sa SRR RSS RRS RRL SSR CCR RE SS RS SSRIS 
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Information about Cautions 


This book may contain cautions. A caution describes a situation that could 
potentially damage your software or equipment. 
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Chapter 1 


Introduction and Installation 





The TMS320C25 is a high-performance CMOS microprocessor, optimized 
for digital signal processing applications. The TMS320C25 is a member of 
the second generation of the TMS320 family of digital signal processors. 


The TMS320C25 is fully supported by a complete set of hardware and soft- 
ware development tools (Section1.1 describes these tools) including 


i. 


a CM rnramniler 

a ww’ ER Ee 

an assembler, a linker, and archiver, 
a full-spoeed emulator, 


a software simulator, and 


i oe oe 


a PC-resident software development system. 


This reference guide describes the details and characteristics of the 
TMS320C25 C compiler. It assumes that you already know how to write C 
programs. We suggest that you obtain a copy of The C Programming Lan- 
guage, by Brian W. Kernighan and Dennis M. Ritchie (published by 
Prentice-Hall), as a supplement to this reference guide. 


Topics in this introductory chapter include: 


Section Page 
1.1. Software Development Tools Overview ...............2.--5 1-2 
12: “DOMWarle NSIAIIAHON ade cu. cnetho a Anes ee Rak emswd awake ee 1-4 


123° “Getting Staned: cote tene th ekie lod ta buae Sees bedankt inp ee 1-8 
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1.1 Software Development Tools Overview 


Figure 1-1 illustrates the TMS320C25 software development flow. The cen- 
ter portion of the figure highlights the most common path of software devel- 
opment; the other portions are optional. 


Figure 1-1. TMS320C25 Software Development Flow 
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The following list describes the tools that are shown in Figure 1—1. Chapter 
2, C Compiler Operation, contains instructions for compiling, assembling, 
linking, and archiving C programs. 


La The C compiler accepts C source code and produces 'MS320C25 as- 
sembly language source code. The C compiler has three parts: a pre- 
processor, aparser, and acode generator. Section 3 describes compiler 
invocation and operation. 


La The assembler translates assembly language source files into ma- 
chine language object files. 


[4 The archiver allows you to collect a group of files into a single archive 
file. (An archive file is called a /ibrary.) |It also allows you to modify a li- 
brary by deleting, replacing, extracting, or adding members. One of the 
most useful applications of the archiver is to build a library of object 
modules. Two object libraries are shipped with the C compiler: 


M £1ib.1ib contains floating-point arithmetic routines. 


M@ xts.lib contains standard runtime-support functions and com- 
piler-utility functions. 


These functions and routines can be called in C programs. You can also 
create your own object libraries. To use an object library, you must spec- 
ify the library name as linker input; the linker will include the library mem- 
bers that define the functions you call in a C program. 


La Thelinker combines objectfiles into a single executable object module. 
As itcreates the executable module, it performs relocation and resolves 
external references. The linker accepts relocatable COFF object files 
and object libraries as input. 


La The main purpose of this development process is to produce a module 
that can be executed ina TMS320C25 target system. You can use one 
of several debugging tools to refine and correct your code; available 
products include: 


@ =6A simulator, 
m@ An extended development system (XDS) emulator, and 
@ A software development system (SWDS). 


La Anobject format converter is also available; it converts aCOFF object 
file into an Intel, Tektronix, or Tl-tagged object format file that can be 
downloaded to an EPROM programmer. 
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1.2 Software Installation 


1.2.1 


1-4 


This section contains step-by-step instructions for installing the 
TMS320C25 C compiler on the following systems: 


La IBM PC 
m PC-DOS (versions 3.x and up) 
@ OS/2 


Ly Digital Equipment Corporation VAX-11 
m VMS operating system 
m Ultrix operating system 


La Sun-3 Workstation 
H Sun-OS (versions 4.x ) 





14 Macintosh 
Ss MPW 


Ra a a Raa ata | 


Note: 





To use the TMS320C25 C compiler, you must also have version 5.0 (or lat- 
er) of the TMS320C25 assembler and linker. 


(iii ia i 


IBM PC with PC-DOS or OS/2 


The C compiler package is shipped on double-sided, dual-density diskettes. 
The compiler requires 512K bytes of available RAM. 


These instructions are for both hard-disk systems and dual floppy drive sys- 
tems (however, we recommend that you use the compiler on a hard-disk 
system). On a dual-drive system, the system diskette should be in drive B. 
The instructions use these symbols for drive names: 


A: Floppy diskette drive for hard disk systems; source drive for dual- 
drive systems. 


B: Destination or system diskette for dual-drive systems. 
C: Winchester (hard disk) for hard-disk systems. 

Follow these instructions to install the software: 

1) Make backups of the product diskettes. 


2) Create adirectory to contain the C compiler. If you’re using a dual-drive 
system, put into drive B the diskette that will contain the tools . 


La On hard-disk systems, enter 
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MD C:\DSPTOOLS 
La On dual-drive systems, enter 
MD B:\DSPTOOLS [=] 


3) Copy the C compiler package onto the hard disk or formatted diskette. 
Put the product diskette in drive A; if you’re using a dual-drive system, 
put the diskette that will contain the tools into drive B. 


La On hard-disk systems, enter 
COPY A:\*.* C:\DSPTOOLS\*.* [auf 
La On dual-drive systems, enter 
COPY A:\*.* B:\DSPTOOLS\*. [a 
4) Put the directory that contains the C tools into your system path. 
La On hard-disk systems, enter 
PATH C:\DSPTOOLS; [aij 
Li On dual-drive systems, enter 
PATH B:\DSPTOOLS; [Ea] 


1.2.2 VAX with VMS 


The TMS320C25 C compiler tape was created with the VMS backup utility 
at 1600 BPI. These tools were developed on version 4.5 of VMS. If you are 
using an earlier version of VMS, you must relink the object files; refer to the 
release notes for relinking instructions. 


Follow these instructions to install the compiler: 
1) Mount the tape on your tape drive. 


2) Execute the following VMS commands. Note that you must create a 
destination directory to contain the package; in this example, 
DEST:DIRECTORY represents that directory. Replace rare with the 
name of the tape drive you are using and prrecrory with the actual 
name of the directory. 


allocate TAPE: 
mount /for/den=1600TAPE: 


backup TAPE:320.bck/SELECT=(MASTER.DSPC...] DEST: [DIRECTORY...] 
dismount TAPE: 
dealloc TAPE: 





3) The producttape contains afile called setup.com. This file sets uo VMS 
symbols that allow you to execute the tools in the same manner as other 
VMS commands. Enter the following command to execute the file: 
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S$ @ setup DEST:directory [=] 
This sets up symbols that you can use to call the various tools. As the file 
is executed, it displays the defined symbols on the screen. 
1.2.3 VAX with Ultrix, Sun-3 with Sun-OS 


The TMS320C25 C compiler product tape was made at 1600 BPI, using the 
TAR command. Follow these instructions to install the compiler: 


1) Mount the tape on your tape drive. 

2) Set the directory where you will store the tools. 

3) Enter the TAR command for your system; for example, 
TAR x 


This copies the entire tape into the directory. The TAR command varies 
from system to system; consult your operating system documentation 
for proper use of the TAR command. 
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1.2.4 Macintosh with MPW 


The C compiler is shipped on a double-sided, 800k, 3 1/2” disk. The disk 
contains three folders. 


Tools Includes Libraries 


Use the Finder to display the disk contents and copy the files into your MPW 
environment. 


1) 


The Tools directory contains all the programs and the batch files for run- 
ning the compiler. Copy this directory in with your other MPW tools 
(MPW tools are usually in the folder {MPW} Tools.) 


The Includes directory contains the header files (.h files) for the run- 
time-support functions. Many of these files have names that conflict with 
commonly-used MPW header files, so you should keep these header 
files separate from the MPW files. Copy the contents of the /ncludes di- 
rectory into a new folder, and use the C_DIR environment variable. 


The Libraries folder contains the compiler’s runtime-support object 
and source libraries. You can copy these files into the folder that you 
created for the header files, or you can copy them into a new folder. lf 
you copy them into a new folder, use the C_DIR environment variable 
to create a path to this folder as well. 
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1.3 Getting Started 
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The TMS320C25 C compiler has three parts: a preprocessor, a parser, and 
a code generator. The compiler produces a single assembly language 
source file that must be assembled. The simplest way to compile and as- 
semble a C program is to use the shell program that is shipped with the com- 
piler. This section provides a quick walkthrough so that you can get started 
without reading the entire reference guide. 


1) Create a sample file called function.c that contains the following 
code: 


[RKKKKK KK KKK KKK KKK KK KK KK KKK KKK KK KK / 
ee Pune lion yc * / 
/* (Sample file for walkthrough) */ 
[RKKKKKKK KKK KK KKK RK KK KK KK RK KKK KK KK / 
int abs (i) 

Ic, 

{ 

register int temp = i; 

if (temp < 0) temp *= -1; 

return (temp); 


} 


2) Toinvoke the shell program to compile and assemble function.c} en- 
ter: 


daspel function [=] 


The shell program prints the following information as it compiles the pro- 
gram: 


dspcel function 

fFuUneCt Lon} 

C Pre-Processor Version 5.10 

(c) Copyright 1987, 1989, Texas Instruments Incorporated 

DSP C Compiler Version 5.10 

(c) Copyright 1987, 1989, Texas Instruments Incorporated 
“function.c”: ==> abs 

DSP C Codegen Version 5.10 


(c) Copyright 1987, 1989, Texas Instruments Incorporated 
“function.c”: ==> abs 
DSP COFF Assembler Version 5.10 

(c) Copyright 1987, 1989, Texas Instruments Incorporated 
PASS 1 

PASS 2 


No Errors, No Warnings 





Introduction and Installation 


asatesanaatatanateretatarasatatasarstatetetatatareteterataratesatetetatatetatonsseterstatetetsteratesatatatatetatasetanssesetstatatetetstetatatetetetetatstetetetesenatesetatetetstetetetetesetetetstetatscoretesetassetatstetetatetatesenatetetatatatatatetegstetetetessrotasetartatatatateteseteteretetataseralateteteteratsretotateretetecetatetsretesetotetstotetetetatatetetetetasetstasetetetatetereterenntaatetetetetoterareteteetere 


The shell program compiles and assembles function.c by invoking 
the following: 


dspcpp —- C Preprocessor 
dspcc — C Parser 
dspcg — Code Generator 
dspa — Assembler 


Inthis example, function.c isthe input source file. Do not specify an 
extension for the input file; the batch file assumes that the input file has a 
.c extension. 


Each tool creates a file that the next tool uses for input; the tools use the 
filename of the source file (without the .c extension) to name the files 
that they create. This example uses and creates the following files: 


a) The source file function.c Is input for the preprocessor; the pre- 
processor creates a modified C source file called function. cpp. 


b) function.cpp is input for the parser; the parser creates an inter- 
mediate file called function.if. 


Cc) function.if Is input for the code generator; the code generator 
creates an assembly language file called function.asm. 


d) function.asmis input for the assembler; the assembler creates an 
object file called function. obj. 


The final output is an object file. This example creates an object file 
called function.ob3. To create an executable object module, link the 
object file created by the batch file with the runtime-support library 
FES 77s 


dspink:. =—<c function —o Eunction: cut 1. rts.lib 


This example uses the —c linker option because the code was originally 
from a C program. It uses the —o option to name the output module 
function.out. If you don’t use the —o option, the linker names the out- 
put module a. out. 
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You can find more information about invoking the compiler tools, the assem- 
bly language tools, and the batch files in the following sections: 


Section Page 
2.1 Compiling and Assembling a Program ................-.--- 2-2 
2.2 Invoking the Compiler Tools Individually .................... 2-5 
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2.4 Archiving a C Program 
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The TMS320C25 compiler is made up of three programs: the preprocessor, 
the parser, and the code generator. After compiling a program, you must as- 
semble and link it with the TMS320C25 assembler and linker. 


If you choose to run the three compiler steps individually, Section 2.2 de- 
scribes how to do so. 


Topics in this chapter include 
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2.1 Compiling and Assembling a Program 


The compiler creates a single assembly language source file as output. You 
can assemble and link this file to form an executable object module. You can 
compile several C source programs, assemble each of them, and then link 
them together. (The TMS320C 1x/TMS32C2x Assembly Language Tools 
User’s Guide describes the TMS320C25 assembler and linker.) 


Example 2—1 and Example 2-2 show two different methods for compiling 
and assembling a C program. Both of these examples compile and as- 
semble a C source file called program.c and create an object file called 
program.obj. Example 2—1 shows how you can accomplish this by invok- 
ing the preprocessor, the parser, the code generator, and the assembler in 
separate steps. Example 2—2 shows how you can use a shell program for 
compiling and assembling a file in one step. 


Example 2-1. Method 1 — Invoking Each Tool Individually 













1) Invoke the preprocessor; use program.c for input: 


dspcpp program [| 

C Pre-Processor, Version 5.10 

(c) Copyright 1987, 1989 Texas Instruments Incorporated 
This creates an output file called program. cpp. 


2) Invoke the parser; use program. cpp for input: 


dspcc program i] 


DSP C Compiler, Version 5.10 
(c) Copyright 1987, 1989 Texas Instruments Incorporated 
“program.c” ==> abs 


This creates an output file called program. if. 
3) Invoke the code generator; use program. if for input: 


dspcg program [=] 


DSP C Codegen, Version 5.10 
(c) Copyright 1987, 1989 Texas Instruments Incorporated 
“program.c” ==> abs 


This creates an output file called program.asm 
4) Assemble program.asm 


dspa program = 


DSP COFF Assembler, Version 5.10 
(c) Copyright 1987, 1989 Texas Instruments Incorporated 
PASS 1 


PASS 2 





No Errors, No Warnings 


This creates an output file named program. obj 
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A shell program is shipped as part of the TMS320C25 C compiler package. 
The shell program expects C source or assembly source files as input, to 
produce object files that can be linked. To invoke the shell program, enter: 





dspcl 


options 


names the shell program that invokes the tools. If you do not 
specify filenames or options, the shell displays a help screen 
with the syntax of the shell command and its options. 


are single letters preceded by hyphens. Options are notcase 
sensitive. Some options have additional fields which follow 
the option with no intervening spaces. Valid options include: 


—C no linking (negates —z) 
—dNAME predefine NAME 


-—g symbolic debugging 
-i dir #include search path 
—k keep .asmfile 
—n compile only (no asm) 
—q quiet 
—dq super quiet 
-—S C source interlist 
—UNAME undefine NAME 
—Z link options follow 


Preprocessor (—p) options: 
—pc preprocess only 
—pp no #line directives 
Runtime (—m) model options: 


—ma aliased variables 
—mr register use info 
—Mv volatile variables 


Assembler options (—a options) 


—al assembly listing file 
—ap preprocess first 
—as keep local symbols 


2-3 


Compiling and Assembling a Program — oe 


eaeeeSes ees eeebeantnseaasesesenenaarararasegasessznaeatatatatasessseset tat alasatesaeatgatatatatatasatat acetates acela tons tatatatatasetatatasetetetotats 


Sees seenatseseorarestesshenececeneceselecenecesecesesesel es eceeecececanstesecececececesececessseseiecsstetetcastateanscestossenavesenenavesssonsnaverensnsnaneraronananasts 


MXM XXNXK ER RAK K RK NRRL RRR RRL MM RR ROS 


—ax cross-reference file 


filenames names C source or assembly files. An extension of .c indi- 
cates a source file, an extension of .asm indicates an assem- 
bly file. lf you do not specify an extension, the shell assumes it 
is a C source file (extension of .c). 


link options — all options following the —z are passed directly to the linker. 


object files names additional object files used in the link step. 


The output files have the same name as the input files but with an extension 
of obj. See Section 2.3 for linker options. 


Example 2-2 shows how the shell program compiles and assembles a C 
source file named program.c by invoking dspcpp, dspcc, dspeg, and 


dspa. 


Example 2-2. Method 2 — Using the Shell Program 


dspcl program [=] 
[program] 
C Pre-Processor, 
(c) Copyright 1987, 
DSP C Compiler, 
(c) Copyright 1987, 
“program.c” == 
DSP C Codegen, 
(c) Copyright 1987, 
“program.c” == 
DSP COFF Assembler, 
(c) Copyright 1987, 
PASS 1 
PASS 2 


Version 5.10 
1989 Texas Instruments 

Version 5.10 
1989 Texas Instruments 
abs 

Version 5.10 


1989 Texas Instruments 


abs 
Version 5.10 
1989 Texas Instruments 


No Errors, No Warnings 





Incorporated 


Incorporated 


Incorporated 


Incorporated 
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2.2 Invoking the Compiler Tools Individually 


Figure 2—1 illustrates the three-step process of compiling a C program. 


Figure 2-1. Compiling a C Program 
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Step 1: The input for the preprocessor is a C source file (as described 
in Kernighan and Ritchie). The preprocessor produces a modified 
version of the source file. 


Step 2: The input for the parser is the modified source file produced by 
the preprocessor. The parser produces an intermediate file. 


Step 3: The input for the code generator is the intermediate file produced 
by the parser. The code generator produces an assembly lan- 
guage source file. 


2.2.1 Preprocessing C Code 


The first step in compiling a TMS320C25 C program is invoking the C pre- 
processor. The preprocessor handles macro definitions and substitutions, 
#include files, line number directives, and conditional compilation. As Figure 
3—2 shows, the preprocessor uses a C source file as input, and produces 
a modified source file that is used as input for the C parser. 
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Figure 2-2. Input and Output Files for the C Preprocessor 
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To invoke the preprocessor, enter: 





dspcpp 
input file 


output file 


options 


is the command that invokes the preprocessor. 


names a C source file that the preprocessor uses as input. If 
you don’t supply an extension, the preprocessor assumes 
that the extension is .c. If you don’t specify an input file, the 
preprocessor prompts you for one. 


names the modified source file that the preprocessor creates. 
If you don’t supply a filename for the output file, the preproces- 
sor uses the input filename with an extension of . cpp. 


are single letters preceded by hyphens. Options are not case 
sensitive. Some options have additional fields that follow the 
option with no intervening spaces. Valid options include 


—C copies comments to the output file. If you don’t use 
this option, the preprocessor strips comments. There 
is no reason to keep comments unless you plan to in- 
spect the . cpp file. 


—dname [=def] 
defines name as if it were #defined in a C source file 
(as in #define name def). You can use name in #if 
and #ifdef statements without explicitly defining it in 
the C source. The =de¢ is optional; if you don’t use it, 
name has a value of 1. 


You can use the —d option multiple times to define 
several names; be sure to separate multiple —d op- 
tions with spaces. 
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-idir adds dir to the list of directories to be searched for 
#include files. You can use this option multiple times 
to define several directories; be sure to separate mul- 
tiple—i options with spaces. Note that if you don’t 
specify a directory name, the preprocessor ignores 
the —i option. (For more information about alternate 
directories, see Section 2.2.1.1.) 


—p tells the preprocessor not to produce line number and 
file information. 


—q suppresses the banner and status information. 
Note that options can appear anywhere on the commandline. 


This preprocessor is the same preprocessor that is described in Kernighan 
and Ritchie; additional information can be found in that book. The prepro- 
cessor supports the same preprocessor directives that are described in Ker- 
nighan and Ritchie (Appendix B summarizes these directives). All prepro- 
cessor directives begin with the # character, which must appear in column 
1 of the source statement. Any number of blanks or tabs may appear be- 
tween the # sign and the directive name. 


The C preprocessor maintains and recognizes five predefined macro- 
names: 


__LINE__ represents the current line number (maintained as a decimal in- 
teger). 
__FILE__ represents the current filename (maintained as a C string). 


__DATE__represents the date that the module was compiled (repre- 
sented as a C character string). 


__TIME__ represents the time that this module was compiled (repre- 
sented as a C character string). 


_dsp identifies the code as TMS320C25 code; it is defined as the 
constant 7. 


You can use these names in the same manner as any other defined name. 
For example, 


Print’ (“es ¢87 4°. - TIME. 2 #2 DATE 3 
could translate to a line such as: 
printf ("%s 3s” , “Jan 14 1988”, "13:58:17"); 


The preprocessor produces self-explanatory error messages. The line 
number and the filename where the error occurred are printed along with 
a diagnostic message. 
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2.2.1.1 Specifying Alternate Directories for Include Files 


The #include preprocessor directive tells the preprocessor to read source 
statements from another file. The syntax for this directive is: 


#include "filename” 
or 
#include <filename> 


The filename names an include file that the preprocessor reads statements 
from; you can enclose the filename in double quotes or in angle brackets. 
The filename can be acomplete pathname or a filename with no path infor- 
mation. 


La If you provide path information for filename, the preprocessor uses that 
path and does not look for the file in any other directories. 


La If you don’t provide path information and you enclose filename in 
double quotes, the preprocessor searches for the file in 


1) The directory that contains the current source file. (The current 
source file refers to the file that is being processed when the prepro- 
cessor encounters the #include directive.) 


2) Any directories named with the —i preprocessor option. 
3) Any directories set with the environment variable C_DIR. 


La If you don’t provide path information and you enclose filename in angle 
brackets, the preprocessor searches for the file in 


1) Any directories named with the —i preprocessor option. 
a) Any directories set with the environment variable C_DIR. 


ee ae ge eee el 


Note: 


lf you enclose the filename in angle brackets, the preprocessor does not 
search for the file in the current directory. 
Eee ec ee ECE eC ae ER NT | 


You can augment the preprocessor’s directory search algorithm by using 
the —i preprocessor option or the environment variable C_DIR. 
-i Preprocessor Option 


The —i preprocessor option names an alternate directory that contains in- 
clude files. The syntax for the —i option is 


dspcpp -i pathname 
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You can use up to 10 -i options per invocation; each —i option names one 
pathname. In C source, you can use the #include directive without specify- 
ing any path information for the file; instead, you can specify the path infor- 
mation with the —i option. For example, assume that a file called source.c 
is in the current directory; source.c contains the following directive state- 
ment: 


rinclude “ali.” 


Note that the include filename is enclosed in double quotes. The complete 
path/filename for alt .cis 


Ll c:\dsp\files\alt.c (DOS systems), 

Ld [dsp.files]alt.c(VMS system), 

Li /dsp/files/ait.c (UNIX systems), or 

LH drive:dsp:files:alt.c(MPW systems). 


This is how you invoke the preprocessor: 


DOS: dspcpp -ic:\dsp\files source.c 


VMS: dspcpp -ildsp.files] source.c 
UNIX: dspcpp -i/dsp/files source.c 
MPW: dspcpp -idrive:dsp:files source.c 





The preprocessor first searches for alt .c inthe current directory, because 
source.c Is inthe current directory. The preprocessor then searches the di- 
rectories named with the —i option. 


Environment Variable 


An environment variable is a system symbol that you define and assign a 
string tc. The preprocessor uses an environment variable named C_ DIR to 
name alternate directories that contain include files. The commands for as- 
signing the environment variable are 


DOS: _ set C_DIR = pathname;another pathname ... 
M 


< 
4 


assign "pathname,;another pathname...” C_DIR 


UNIX: setenv C_DIR ’pathname;another pathname ...” 
MPW: _ set C DIR "pathname,another vathname ...” 
export C_DIR 


The pathnames are directories that contain include files. You can separate 
pathnames with a semicolon or with blanks. in C source, you can use the 
#include directive without specifying any path information; instead, you can 
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specify the path information with C_DIR. For example, assume that a file 
called source.c contains these statements: 


#include <altl.c> 
#include <alt2.c> 


Assume that the complete path and file information for these files is 


c:\320\files\altl.c and c:\dsys\alt2.c (DOS systems) 
[320.files]altl.c and [dsys]alt2.c (VMS system), 
/320/files/altl.c and /dsys/alt2.c (UNIX systems), or 
drive:320:files:altl.c and drive:dsys:alt2.c (MPW systems). 


This is how you set the environment variable and invoke the preprocessor: 


DOS: set C_DIR=c:\dsys; c:\exec\files 
dspcpp ~—ic:\320\files source.c 


< 
op) 


- assign “[dsys]; [exec.files]” C DIR 
dspepp —1[(320.files) source.¢ 


UNIX: setenv C_DIR "c:/dsys; c:/exec/files” 
dspcpp -—ic:/320/files source.c 
MPW: set C_DIR ”:dsys;:files” 


export C_DIR 
dspepp drive/320/files source.c 


Note that the include filenames are enclosed in angle brackets. The prepro- 
cessor first searches in the directories named with the —i option and finds 
alti.c. Then, the preprocessor searches in the directories named with 
C_DIR and finds ait2.c. 


The environment variable remains set until you reboot the system or reset 
the variable by entering | 


DOS: _ set C DIR= 
VMS: deassign C_DIR 

Ni setenv C DIR”” 
unset C DIR 


Cc 
2s 


= 
= 
= 
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2.2.2 Parsing C Code 


The second step in compiling a TMS320C25 C program is invoking the C 
parser. The parser reads the modified source file produced by the prepro- 
cessor, parses the file, checks the syntax, and produces an intermediate file 
that can be used as input for the code generator. (Note that the input file can 
also be a C source file that has not been preprocessed, if the file contains 
no preprocessor directives.) Figure 2-3 illustrates this process. 


Figure 2—3. Input and Output Files for the C Parser 


modified ess lasiols 
source file 


(.cpp) 





To invoke the parser, enter 





dspcc is the command that invokes the parser. 


input file names the modified C source file that the parser uses as input. 
lf you don’t supply an extension, the parser assumes that the 
extension is .cpp. If you don’t specify an input file, the parser 
prompts you for one. 


output file names the intermediate file that the parser creates. If you do 
not supply a filename for the output file, the parser uses the 
input filename with an extension of .if. 
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options are single letters preceded by hyphens. Options can appear 
anywhere on the command line and are not case sensitive. 
Valid options include 


—Z tells the parser to retain the input file (the intermedi- 
ate file created by the preprocessor). If you don’t 
specify —z, the parser deletes the . cpp inputfile. (The 
parser never deletes files with the .c extension.) 


— suppresses the banner and status information. 


Most errors are fatal; that is, they prevent generation of an intermediate file 
and must be corrected before you can finish compiling a program. Some er- 
rors, however, merely produce warnings that hint of problems but don’t pre- 
vent the parser from producing an intermediate file. 


As the parser encounters function definitions, it prints a progress message 
that contains the name of the source file and the name of the function. Here 
is an example of a progress message: 


filename:c : = > main 


This type of message shows how far the compiler has progressed in its ex- 
ecution and helps you to identify the locations of errors. Use the —q option 
to suppress these messages. 


If the input file has an extension of . cpp., the parser deletes it upon comple- 
tion unless you use the —z option. If the input file has an extension other than 
.cpp, the parser does not delete it. 





2.2.3 Generating Assembly Language Code 
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The third step in compiling a TMS320C25 C program is invoking the C code 
generator. As Figure 2—4 shows, the code generator converts the interme- 
diate file produced by the parser into an assembly language source file. You 
can modify this output file or use it as input for the TMS320C25 assembler. 
The code generator produces reentrant, relocatable code that can be ex- 
ecuted from ROM. 
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Figure 2—4. Input and Output Files for the C Code Generator 











intermediate code 
file o[=lat-}eci cele 
(if) (efeKe) 





4 assembly 
4 language code 
4 (.asm) 





dspcg 


input file 


output file 


tempfile 


options 


is the command that invokes the code generator. 


names the intermediate file that the code generator uses as 
input. The code generator assumes that the input file has an 
extension of .if ; if you supply a different extension, the code 
generator ignores it. If you don’t specify an input file, the code 
generator prompts you for one. 


names the assembly language source file that the code gen- 
erator creates. If you don’t supply afilename for the output file, 
the code generator uses the input filename with an extension 
of .asm. 


names a temporary file that the code generator creates and 
uses. The default filename for the temporary file is the input 
filename appended with an extension of . tmp. The code gen- 
erator deletes this file after it uses it. 


are case-sensitive single letters preceded by hyphens. Valid 
options include: 


—O tells the code generator to place symbolic debugging 
directives in the output file. See Appendix B of the 
TMS320C 1x/TMS320C2x Assembly Language 
Tools User’s Guide for more information about these 
directives. 
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—q suppresses the banner and status information. 


—Z tells the code generator to retain the input file (the in- 
termediate file created by the parser). This option is 
useful for creating several output files with different 
options; for example, you might want to use the same 
intermediate file to create one file that contains sym- 
bolic debugging directives (—o option) and one with- 
out them. Note that if you don’t specify the —z option, 
the code generator deletes the input (intermediate) 
file. 


—r writes register information to output file in the form of 
comments. 
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2.3 Linking a C Program 


The TMS320C25 C compiler and assembly language tools support modular 
programming by allowing you to compile and assemble individual modules 
and then link them together. To link compiled and assembled code, enter 





dspink is the command that invokes the linker. 


~c and-—cr are options that tell the linker to use special conventions that 
are defined by the C environment. 


filenames are object files created by compiling and assembling C pro- 
grams. 


options Vaiid options inciude 
—O allows you to specify the output filename including 


the extension. If this option is not used, the default 
output filename is a.out. 


—| allows you to specify an archive library as linker input. 


rts.lib is an archive library that contains C runtime-support func- 
tions; it is shipped with the C compiler. Note that you can also 
link in £1ib.1ib (the floating-point support library) or your 
own object libraries. The linker includes and links only those 
library members that resolve undefined references. 


For example, you can link a C program consisting of modules prog1.obj, 
prog2.ob}, and prog3.obj (the output file is named prog. out): 


dsplnk -c progl prog2 prog3 -1 rts.lib -o prog.out 


The linker uses a default allocation algorithm to allocate your program into 
memory. You can use the MEMORY and SECTIONS directives to custom- 
ize the allocation process. For more information about the linker, see the 
TMS320C 1x/TMS320C2x Assembly Language Tools User’s Guide. 


2.3.1. Runtime Initialization and Runtime Support 


All C programs must be linked with an object module called boot .obj. The 
boot.obj module is a member of the runtime-support object library, 
rts.lib. To use the module, simply use —c or —cr and include the library in 
the link: 


dspink.=c:=l 2is.12o: 24 
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When aC program begins running, It must execute boot . obj first. The sym- 
bol _c into marks the starting point in boot .ob3; if you use the —c or -cr 
option, then _c_ into is automatically defined as the entry point for the pro- 
gram. If your program begins running from reset, you can set up the reset 
vector to generate abranchto_ c_ into so that the TMS320C25 executes 
boot .obj first. The boot .ob3j module contains code and data for initializing 
the runtime environment; the module performs the following tasks: 


Lk Sets up the system stack. 


La Processes the runtime initialization table and autoinitializes global vari- 
ables (in the ROM model). 


Ly Calls main (the C program). 


Cy «Calls exit if main returns. 


The linker automatically extracts boot .obj from rts.1ib and links it when 
you use the —c or —cr option. 


a a Aa a A a aaa | 


Note: 


You must specify rts.1ib on the command line. 
SR cee a a ee EE a ee Oe TS | 


Chapter 5 describes additional runtime-support functions that are included 


IN rts.lib. 


2.3.2 Sample Linker Command File 


Figure 2—5 shows a typical linker command file that can be used to link a 
C program. The command file in this example is named link. cmd. 


Figure 2—5. An Example of a Linker Command File 
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J: Linker command file link.cmd kf 
[RK KKK KK KKK KK KR KR KKK KK CK RR KR RR RK KR RK KK KKK KKK / 


= /* 
—m example.map /* 
—-o example.out /* 


main.obj 
sub.obj 
asm.obj 

=) PES cla 

cert Mabe cil Nd © ol Eo 8 
-l matrix.lib 


ROM autoinitialization model */ 
Create a map file * / 
Output file name * / 


First C module 

Second C module 
Assembly language module 
Runtime-support library 
Floating-point library 
Object library 
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La The command file in Figure 2—5 first lists several linker options: 


—c is one of the options that can be used to link C code; it tells the 
linker to use the ROM autoinitialization method. 


-—m_ tells the linker to create a map file; the map file in this eae is 
named example.map. 


—oO tells the linker to create an executable object module; the module 
in this example is named example. out. 


[i Next, the command file lists all the object files to be linked. This C pro- 
gram consists of two C modules, main.c and sub.c, which were com- 
piled and assembled to create two object files called main.obj and 
sub.obj. This example also links in an assembly language module 
called asm. ob}. 


One of these files must define the symbol main, because boot . obj Calls 
main as the start of your C program. All of these single object files are 
linked. 


La Finally, the command file lists all the object libraries that the linker must 
search. (The libraries are specified with the —| linker option.) Because 
this is a C program, the runtime-support library rts.1ib must be in- 
cluded. If a program uses floating-point routines, it must also link in 
flib.1lib (the floating-point library). This program uses several rou- 
tines from an archive library called mat rix.1lib, So itis also named as 
linker input. Note that only the library members that resolve undefined 
references are linked. 


To link the program, enter 
dsplnk link.cmd 


This example uses the default memory allocation described in Section 8.8 
of the TMS320C 1x/TMS320C2x Assembly Language Tools User’s Guide. 
If you want to specify different MEMORY and SECTIONS definitions, refer 
to that user’s guide. 


2.3.3 Autoinitialization (ROM and RAM Models) 


The C compiler produces tables of data for autoinitializing global variables. 
(Section 4.8.2, page 4-19, discusses the format of these tables.) These 
tables are in a named section called .cinit. The initialization tables can be 
used in either of two ways: 


L4 ROM Model (-c option) 


Giobal variables are initialized at runtime. The .cinit section is loaded 
into memory along with all the other sections. The linker defines a spe- 
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cial symbol called cinit that points to the beginning of the tables in 
memory. When the program begins running, the C boot routine copies 
data from the tables into the specified variables in the .bss section. This 
allows initialization data to be stored in ROM and then copied to RAM 
each time the program is started. 


Figure 2-6 illustrates the ROM autoinitialization model. 


Figure 2-6. ROM Model of Autoinitialization 
Object File Memory 
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Tables 
possibly ROM 


loader 





Boot 
Routine 


Ly RAM Model (-cr option) 


Global variables are initialized at load time. This enhances performance 
by reducing boot time and saving memory used by the initialization 
tables. (Note that you must use a smart loader to take advantage of the 
RAM model of autoinitialization.) 


When you use -cr, the linker marks the .cinit section with a special attrib- 
ute. This attribute tells the linker not to allocate the .cinit section into 
memory. The linker also sets the cinit symbol to -1; this tells the C boot 
routine that initialization tables are notpresent in memory. Thus, no run- 
time initialization is performed at boot time. 


When the program is loaded, the loader must be able to 
m Detect the presence of the .cinit section in the object file. 


m Detect the presence of the attribute that tells it not to load the .cinit 
section. 


m Understand the format of the initialization tables (described in Sec- 
tion 4.8.2 on page 4—19). 
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The loader then uses the initialization tables directly from the object file 
to initialize variables in .bss. 


Figure 2-7 illustrates the RAM autoinitialization model. 


Figure 2-7. RAM Model of Autoinitialization 
Object File Memory 





2.3.4 The-c and —-cr Linker Options 


The following list outlines what happens when you invoke the linker with the 
—c or—cr option. These are the linking conventions required for C programs. 


La The symbol _c_intO is defined as the program entry point; it identifies 
the beginning of the C boot routine in boot .obj. When you use -c or 
—cr, c_intO is automatically referenced; this ensures that boot . obj is 
automatically linked in from the runtime-support library. 


La The .cinit output section is padded with a termination record so that the 
boot routine (ROM model) or the loader (RAM model) knows when to 
stop reading the initialization tables. 


La In the ROM model (-c option), the linker defines the global symbol 
cinit as the starting address of the .cinit section. The C boot routine 
uses this symbol as the starting point for autoinitialization. 


La Inthe RAM model (—cr option): 


m Thelinkersets the symbol cinit to—1. This indicates that the initial- 
ization tables are notin memory, so no initialization is performed at 
runtime. 


m The STYP_COPY flag (010h) is set in the .cinit section header. 
STYP_COPY is the special attribute that tells the loader to perform 
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autoinitialization directly and not to load the .cinit section into 
memory. The linker does not allocate space in memory for the .cinit 
section. 


2.4 Archiving a C Program 
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An archive file (or library) is a partitioned file that contains complete files as 
members. The TMS320C1x/TMS320Cex archiver is a software utility that 
allows you to collect a group of files together into a single archive file. The 
archiver also allows you to manipulate a library by adding members to it or 
by extracting, deleting, or replacing members. The TMS320C1x/ 
TMS320C 2x Assembly Language Tools User’s Guide contains complete in- 
structions for using the archiver. 


After compiling and assembling multiple files, you can use the archiver to 
collect the object files into a library. You can specify an archive file as linker 
input. The linker is able to discern which files in a library resolve external ref- 
erences, and it links in only those library members that it needs. This is use- 
ful for creating a library of related functions; the linker links in only the func- 
tions that a program calls. The library rts.1ib is an example of an object 
library. 


You can also use the archiver to collect C source programs into alibrary. The 
C compiler cannot choose individual files from a library; you must extract 
them before compiling them. However, this can be useful for file manage- 
mentand portability. The library rts. src is anexample of an archive file that 
contains source files. 


For more information about the archiver, see the TMS320C 1x/TMS320C2x 
Assembly Language Tools User’s Guide. 
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The C language that the TMS320C25 C compiler supports is based on the 
UNIX System VC language that is described by Kernighan and Ritchie, with 
several additions and enhancements. The most significant differences are 


C4 The addition of data type enum. 
[4 Unique member names are not required in structures. 


La Structures and unions can be passed as parameters to functions and 
assigned directly. 


This chapter compares the C language compiled by TMS320C25 C to the 
C language described by Kernighan and Ritchie. It presents only thea/ffer- 
ences in the two forms of the C language. The TMS320C25 C compiler sup- 
ports standard Kernighan and Ritchie C except as noted in this section. 


Throughout this chapter, references to Kernighan and Ritchie's C Refer- 
ence Manual (Appendix A of The C Programming Language) are shown in 
the left margin. 


Topics in this chapter include 
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3.1 Identifiers, Keywords, and Constants 
K&R 2.2 — Identifiers 


La In TMS320C25 C, the first 31 characters of an identifier are signifi- 
cant (in K&R C, 8 characters are significant). This also applies to exter- 
nal names. 


La Case is significant; uppercase characters are different from lower- 
case characters for identifier names in all TMS320C25 C tools. This 
also applies to external names. 


K&R 2.3 — Keywords 
TMS320C25 C reserves three additional keywords: 
asm 
void 
enum 


K&R 2.4.1 — Integer Constants 


La All integer constants are of type int (signed, 16 bits long) unless they 
have an Lor Usuffix. If the compiler encounters an invalid digit in a con- 
stant (such as 8 or 9 in an octal constant), it issues a warning message. 


La Youcan append aletter suffix to an integer constant to specify what kind 
of integer it is: 


Use Uas a suffix to declare an unsigned integer constant. 
m Use L as a suffix to declare a long constant. 


M Combine the suffixes to declare an unsigned long integer 
constant. 


Note that the suffixes can be upper or lower case. 


Lua Here are some examples of integer constants: 


1234; am baie Df, 
OxFFFFFFFFu; /* unsigned int * / 
Oise /* long int a 
OF 1623 LU; /* unsigned long int * / 


K&R 2.4.3 — Character Constants 


In addition to the escape codes listed in K&R, the TMS320C25 C compiler 
recognizes the escape code \v in character and string constants as averti- 
cal tab character (ASCII code 11). 
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K&R 2.4.4 — Floating-Point Constants 


In TMS320C25 C, floats, doubles, and long doubles are single-precision 
(32-bit) floating-point numbers. To provide compatibility with ANSI standard 
C, the compiler allows you to append one of two suffixes to a floating-point 
constant: 

i L identifies long double constants in ANSI C. 

La F identifies floats in ANSI C. 


You can use either upper or lower case letters. Examples of floating-point 
constants include: 


Li 234; /* double * / 
1.0e14£; Ps @ oak * / 
3,141.50 /* double ay 


Note that using a suffix does not change the way the compiler treats the 


Added Type — Enumeration Constants 


Enumeration constants are an additional type of integer constant that is 
not described by K&R. An identifier declared as an enumerator can be used 
in the same manner that an integer constant can be used. (For more infor- 
mation about enumerators, see Section 3.5 on page 3-6.) 


K&R 2.5 — String Constants 


Ca K&R C does not limit string constant length; however, TMS320C25 C 
limits the length of string constants to 255 bytes. 


La All characters after an embedded null byte in a string consiant are ig- 
nored; in other words, the first null byte terminates the string. However, 
this does not apply to strings used to initialize arrays of characters. 


La Identical string constants are stored as a single string, not as sepa- 
rate strings as in K&R C. However, this does not apply to strings used 
for autoinitialization of arrays of characters. 
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3.2 Data Types 
K&R 4.0 — Equivalent Types 


a 


Ca 


Cl 
Ca 


The char data type is signed. A separate type, unsigned char, is also 
supported. 


long, int, short, and char. are all functionally equivalent types. Any of 
these types can be declared unsigned. 


float and double are functionally equivalent types. 


The properties of enum types are identical to those of unsigned int. 


K&R 4.0 — Added Types 


Oh 


An additional type, called void, can be used to declare a function that 
returns no value. The compiler checks that functions declared as void 
do not return values and that they are not used in expressions. Func- 
tions are the only type of objects that can be declared void. 


The compiler also supports a type that is a pointer to a void (void"). 
An object of type void * can be converted to and from a pointer to an ob- 
ject of any other type without explicit conversions (casts). However, 
such a pointer cannot be used indirectly to access the object that it 
points to without a conversion. For example, 


void *p, *malloc(); 
char CF 


int 1; 

p = malloc(); /* Legal * / 
De soc, /* Legal x / 
p = &i; /* Legal * / 
o=amalloc() /* Legal ay 
i = *p; /* Illegal a | 
1 = * (int *)p; /* Legal * / 


K&R 4.0 — Derived Types 
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TMS320C25 C allows any type declaration to have up to six derived types. 


Constructions such as pointer to, array of, and function returning can be 


combined and applied a maximum of six times. 
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For example: 


at 308 Ca Lb ek de aye 


translates as 
1) an array of 

) arrays of 

) pointers to 

) functions returning 

) pointers to 

6) functions returning integers 


OoarhwaN — 


It has six derived types, the maximum allowed. 


Structures, unions, and enumerations are not considered derived types for 
the purposes of these limits. 


Also, the derived type cannot contain more than three array derivations. 
Note that each dimension in a multidimensional array is a separate array 
derivation; thus, aliays are limited to three dimensions in ay type definition. 


IOweVEr, iypes Can be combined using iypedeis ts produce any aimen- 


sioned array. 


For example, the following construction declares x as a four-dimensional 
array: 


typedef int dim2[][]; 
dam TEs 


K&R 2.6 —- Summary of TMS320C25 Data Types 





Type Size 

char 16 bits, signed 

unsigned char 16 bits 

short 16 bits 

unsigned short 16 bits 

int 16 bits 

unsigned int 16 bits 

long 16 bits 

unsigned long 16 bits 

pointers 16 bits 

float 32 bits 

double Range: +1.17549435 x 409(-38) through 

+3.40282347 x 1038 

enum 16 bits 
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3.3 Object Alignment 


All objects except bit fields are aligned on 16-bit (one word) boundaries. Bit 
fields are always unsigned and can be from 1 to 16 bits in length. Adjacent 
fields are packed into adjacent bits of a word, but they do not overlap words; 
if a fleld would overlap into the next word, the entire field is placed into the 
next word. (A bit field never crosses a word boundary.) Fields are packed 
as they are encountered; the least significant bits of the structure word are 
filled first. 


When the compiler allocates space for a structure, it allocates as many 
words as are needed to hold all of the structure’s members. In an array of 
structures, each structure begins on a word boundary. 


3.4 Expressions 
Added type — Void Expressions 


A function of type void has no value (returns no value) and cannot be called 
in any way except as a separate statement or as the left operand of the com- 
ma operator. Functions can be declared or typecast as void. 


K&R 7.2 — Unary Operators in Expressions 


The value yielded by the sizeof operator is calculated as the total number 
of bits used to store the object divided by 16 (16 is the number of bits in a 
character). The sizeof operator can be legally applied to enum objects and 
bit fields; if the result is not an integer, it is rounded up to the nearest integer. 


3.9 Declarations 
K&R 8.1 — Register Storage Class Specifiers 


La The first two local objects declared as type register in a function will be 
allocated to TMS320C25 registers. 


La Any type variable (int, unsigned, char, pointer, float, array, etc.) can be 
declared as a register, since this stores the address of that variable in 
the register. Formal parameters to functions can also be declared as 
type register. 


La Register declarations are ignored in nested blocks. 
For more information about register variables, see Section 4.2.3 on page 
4-7. 
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K&R 8.2 — Type Specifiers in Declarations 


Cd 


(ad 


In addition to the type specifiers listed in K&R, objects can be declared 
with enum specifiers. 


TMS320C25 C allows more type name combinations than K&R C al- 
lows. The adjectives jong and shortcan be used with or without the word 
int; the meaning is the same in either case. The word unsigned can be 
used in conjunction with any integer type or alone; if alone, intis implied. 
long float is a synonym for double. Otherwise, only one type specifier 
is allowed in a declaration. 


K&R 8.4, K&R 10 — Type Specifiers in Function Declarations 


Cd 
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Structures and unions can be used as parameters to functions and can 
be directly assigned. 


Formal parameters to a function can be declared as type structor enum 
(in addition to the normal function declarations), since TMS320C25 C 
allows these types of objects to be nassed to functions. 


K&R 8.5, K&R 14.1 — Structure and Union Declarations 


Ld 


Cd 


Bit fields are limited to a maximum size of 16 bits. Any integer type can 
be declared as a field. Fields are always treated as unsigned, regard- 
less of definition. 


K&R states that structure and union member names must be mutually 
distinct. In TMS320C25 C, members of different structures or 
unions can have the same name. However, this requires that refer- 
ences to any member of a structure or union be fully qualified through 
all levels of nesting. 


TMS320C25 C allows assignment to and from structures and passing 
structures as parameters. 


K&R contains a statement about the compiler determining the type of 
a structure reference by the member name. Because TMS320C25 C 
does not require member names to be unique, this statement does not 
apply. All structure references must be fully qualified as members of the 
structure or union in which they were declared. 


Added Type — Enumeration Declarations 


Enumerations allow the use of named integer constants in TMS320C25 C. 
The syntax of an enumeration declaration is similar to that of a structure or 
union. The keyword enumis substituted for struct or union, and a list of enu- 
merators is substituted for the list of members. 


Enumeration declarations have a tag, as do structure and union declara- 
tions. You can use this tag in future declarations without repeating the entire 
declaration. 


One 
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The list of enumerators is simply acomma-separated list of identifiers. Each 
identifier can be followed by an equal sign and an integer constant. If no enu- 
merator is followed by an = sign and a value, then the first enumerator is as- 
signed the value 0, the next is 1, the next is 2, etc. An identifier with an as- 
signed value assumes that value, and subsequent enumerators continue 
counting by one from there. The assigned value can be negative, but count- 
ing still continues by positive one. 


Unlike structure and union members, enumerators share their name space 
with ordinary variables and, therefore, must not conflict with vanepies or oth- 
er enumerators in the same scope. 


Enumerators can appear wherever integer constants are required and, 
therefore, can be used in arithmetic expressions, case expressions, etc. In 
addition, explicit integer expressions can be assigned to variables of type 
enum. The compiler does no range checking to insure the value will fit in the 
enumeration field. The compiler does, however, issue a warning message 
if an enumerator of one type is assigned to a variable of another. 


Here’s an example of an enumerator declaration: 


enum color 4 
red, 
blue, 
green=10, 
orange, 
purple=-2, 
cyan } <5 


This statement declares x as a variable of type enum. The enumerators and 
their assigned values are: 


red (0) 
blue (1) 
green (10) 
orange (11) 
purple (-2) 
cyan (-1) 


sixteen bits are allocated for the variable x. Legal operations on these enu- 
merators include: 


x = blue; 

x = blue + red 

x = 100; 

i = red; /* assume i is an int * 
x = 1 + cyan; 
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3.6 Initialization of Static and Global Variables 
K&R 8.6 


An important difference between K&R C and TMS320C25 C is that in 
TMS320C25 C, external and static variables are not preinitialized to 
zero unless the program explicitly does so or it is specified by the linker. 


lf a program requires external and static variables to be preinitialized, the 
linker can be used to accomplish this. In the linker control file, use a fill value 
of 0 in the .bss section: 


SECTIONS { 


3.7 asm Statement (Inline Assembly Language) 


Additional Statement 


TMS320C25 C has another statement not mentioned in K&R: the asm 
statement. The compiler copies asm statements from the C source directly 
into the assembly language output file. The syntax of the asm statement is 


asm ("assembler text”); 


The assembler texi must be enclosed in double quotes. All the usual charac- 
ter string escape codes retain their definitions. The assembler text is copied 
directly to the assembler source file. Note that the assembler source state- 
ment must begin with a label, a blank, or a comment indicator (asterisk or 
semicolon). 


Each asm statement injects one line of assembly language into the compiler 
output. A series of asm commands places the statements sequentially into 
the output with no intervening code. 


asm statements do not follow the syntactic restrictions of norma! statements 
and can appear anywhere in the C source, even outside blocks. 
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3.8 Lexical Scope Rules 
K&R 11.1 


The lexical scope rules stated in K&R apply to TMS320C25 C also, except 
that structures and unions each have distinct name spaces for their mem- 
bers. In addition, the name space of both enumeration variables and enu- 
meration constants is the same as for ordinary variables. 


3-10 TMS320C25 C Language 


se SStaaaeseuesesessesseeaceecetessaaasasasasasseseteceeesaesaasasusasesesasasa eas asusossecateaasasosesarasatasssetetesa tatetatasetetotatatetatatosatetetetesosstesstetetetstan 


Chapter 4 





This section describes the TMS320C25 C runtime environment. To ensure 
successful execution of C programs, it is critical that all runtime code main- 
tain this environment. If you write assembly language functions that inter- 
face to C code, follow the guidelines in this chapter. 


Topics in this chapter include: 


Section Page 
4.1 Memory Model ...... abe aidtid wished Aled Saat, aerate Smee ane 4-2 
4.2 Register Conventions ............. 0... c ccc ccc cece eens 4-6 
4.3. Function Call Conventions ............ 0... cece eee eee eens 4-8 
4.4 Interfacing C with Assembly Language ....................... 4-11 
4.5 Interrupt Handling ........... 0... ccc cece eee eee eens 4-16 
4.6 Integer Expression Analysis........ ulin an cosa iets gates ne oe 4-18 
4.7 Floating-Point Expression Analysis .....................00000e 4-19 
4.8 System Initialization ........... 0... ccc ce eee eens 4-20 
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4.1 


Memory Model 


The TMS320C25 treats memory as two linear blocks of program memory 
and data memory: 


Ly Program memory contains executable code. 


Ls Data memory contains external variable, static variables, and the sys- 
tem stack. 


Each block of code or data generated by aC program is placed into acontig- 
uous block in the appropriate memory space. 


Note that the linker, not the compiler, defines the memory map and allo- 
cates code and data into target memory. The compiler assumes nothing 
about the types of memory available, about any locations not available for 
code or data (holes), or about any locations reserved for I/O or control pur- 
poses. The compiler produces relocatable code that allows the linker to allo- 
cate code and data into the appropriate memory spaces. For example, you 
can use the linker to allocate global variables into fast internal RAM, or allo- 
cate executable code into internal ROM. Each block of code or data could 
be allocated individually into memory, but this is not a general practice (an 
exception to this is memory-mapped I/O, although physical memory loca- 
tions can be accessed with C pointer types). 


4.1.1 Sections 
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The compiler produces three relocatable blocks of code and data; these 
blocks, called sections, can be allocated into memory in a variety of ways, 
to conform to a variety of system configurations. For more information about 
sections, please read Section 3 (the Introduction to Common Object File 
Format) of the TMS320C 1x/TMS320C2x Assembly Language Tools User’s 
Guide. 


There are two basic types of sections: 
Li Initialized sections contain data or executable code. 


Li Uninitialized sections reserve space in memory (usually RAM). A pro- 
gram can use this space at run time for creating and storing variables. 


The C compiler creates two initialized sections, .text and .cinit; itcreates one 
uninitialized section, .bss. 


Ly The .text section is an initialized section that contains all the execut- 
able code as well as string literals and floating-point constants. 


La The .cinit section is an initialized section that contains tables for initial- 
izing variables and constants. 
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La The .bss section is an uninitialized section; in a C program, it serves 
three purposes: 


m it reserves space for global and static variables. At boot time, the 
the C boot routine copies data out of the .cinit section (which may be 
in ROM) and uses it for initializing variables in .bss. 


m Itreserves space for the system stack, which is used to pass argu- 
ments to functions and to allocate local variables. 


mM Itreserves space for use by the dynamic memory functions (malloc, 
calloc, and realloc). 


Note that the assembler creates three default sections (.text, .bss, and 
.data); the C compiler, however, does not create a .data section because the 
C environment does not use this section. 


The linker takes the individual sections from different modules and com- 
bines sections with the same name to create three output sections. The 
complete program is made up of these three output sections, plus the .data 
section that the assembler creates. You can place these output sections 
anywhere in the address space, as needed, to meet system requirements. 
The .text, .cinit, and .data sections are usually linked into either ROM or 
RAM. The .bss section should be linked into some type of RAM. 


For more information about allocating sections into memory, see Chapter 
9 (the Linker Description) of the TMS320C 1x/TMS320C2x Assembly Lan- 
guage Tools User’s Guide. 


4.1.2 Allocating Memory for Static and Global Variables 


A unique, contiguous space is allocated for each external or static variable 
that is declared in a C program. The linker determines the address of the 
space. The compiler ensures that space for these variables is allocated in 
multiples of words so that each variable is aligned on a word boundary. 


The C compiler expects global variables to be allocated into data memory. 
(It reserves space for them in .bss.) Variables declared in the same module 
are allocated into a single, contiguous block of memory. 


4.1.3 RAM and ROM Models 


The C compiler produces code that is suitable for use as firmware ina ROM- 
based system. In such a system, the initialization tables in the .cinit section 
are stored in ROM. At system initialization time, the C boot routine copies 
data from these tables from ROM to the initialized variables in .bss (RAM). 


In situations where a program is loaded directly from an object file into 
memory and then run, you can avoid having the .cinit section occupy space 
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inmemory. A loader can read the initialization tables directly from the object 
file (instead of from ROM) and perform the initialization directly at load time 
(instead of at run time). You can specify this to the linker by using the —-cr 
linker option. For more information, see Section 2.3.3 on page 2-17. 


4.1.4 Managing the Runtime Stack 
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The C compiler uses a stack to: 


Ly Allocate local variables. 
La Pass arguments to functions, and 
La Save the processor status. 


The runtime stack grows up from low addresses to higher addresses. The 
compiler uses two auxiliary registers to manage this stack: 


AR1_ isthe stack pointer (SP); it points to the current top of the stack or to 
the word that follows the current top of the stack. 


ARO is the frame pointer (FP); it points to the beginning of the current 
| frame. Each function invocation creates a new frame at the top of the 
stack, from which local and temporary variables are allocated. 


The C environment manipulates these registers automatically; if you write 
any assembly language routines that use the runtime stack, be sure to use 
these registers correctly. (For more information about using these registers, 
see Section 4.2. on page 4—6; for more information about the stack, see 
Section 4.3. on page 4-8.) 


The C initialization routine, boot .asm, allocates memory for the stack in 
.bss. The routine also defines a constant named STACK_SIZE that deter- 
mines the amount of space reserved for the stack. The default stack size 
is 1000 words. You can change the stack size by following these steps: 


1) Extract boot .asm from the source library rts.src. 


2) Edit boot .asm; change the value of the constant stacK_s1zE to the de- 
sired stack size. 


3) Reassemble boot .asmand replace the resulting object file, boot .ob3, 
in the object library rts.1lib. 


Note that the internal TMS320C25 stack is used only temporarily. Return 
addresses that are pushed onto it by CALL instructions are popped off and 
pushed onto the runtime stack. 


Runtime Environment 


Bide tess _Memory Model 


ce sus teGein ints gout deézusGeustccr eric eessorgnaser dr ebdunezsva'scelvaraiab 0s ob eséoatunpsoniasehunsnabusy-ooerguctaraheber as oounarsncmeelwesus wus priieee sameness Ones seenc tide de sabe swen mons suos obese uomnseebesicSue sheen luskeasa bbls gnseasesetacabudepntnnsecosaspcvcazbssteadacouers cece, ogsumuavaeusuee atwcriysudldad aucost s Sousa sbetalninucsmartesetiandeseibcusctwuris tele Dyvls outa neni bs tials Sinem iauaats Seed 0 kdess Sues ate g Wu us aN cuca a cote cah ode 00 auCaCRLe 
sesesegeaseneesaseceeaaseecsaseneneetaaaceeeiaeseeeeeeaseseacasssueacasesasheasasasassearesesesseasanasesosanatesseseatasasssaratarasateretasasetatesetetatenetetenecatetetstetesstetetatatetetatatetetetatesetetaseteletetatetatetosetetatetsestetetetatetetetetatatetetetetatatatetatatetetetatetetetetatatatetetetatatecetetatetetetateteteceratatesstatesetetetatatatetetetstetetatetatatetatatetetenatatetatetetatetetatatetetecatetetetetatetstststatetatatetetetatetetetatetatetetalecetetetetetatetetatasetetetetatetetetstenetets 


4.1.5 Dynamic Memory Allocation 


The runtime-support library supplied with the compiler contains several 
functions (such as malloc, calloc, and realloc) that allow you to dynamically 
allocate memory for variables at runtime. This is accomplished by declaring 
a large memory pool, or heap, and then using the functions to allocate 
memory from the heap. Dynamic allocation is not a standard part of the C 
language; it is provided by standard runtime-support functions. 


AC module called memory .c reserves space for this memory poolinthe.bss 
section. The module also defines a constant named MEmMorY_s1ZeE that de- 
termines the size of the memory pool; the default size is 1000 words. You 
can change the size of the memory pool by following these steps: 


1) Extract memory.c from the source library rts.src. 


2) Edit memory.c; change the value of the constant Memory _ sS1zZE to the 
desired memory pool size. 
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file, memory .obj, in the object library rts.1lib. 
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4.1.6 Packing Structures and Manipulating Fields 


When the compiler allocates space for a structure, it allocates as many 
words as are needed to hold all of the structure’s members. In an array of 
structures, each structure begins on a word boundary. 


All non-field types are aligned on word boundaries. Fields are allocated as 
many bits as requested. Adjacent fields are packed into adjacent bits of a 
word, but they do not overlap words; if a field would overlap into the next 
word, the entire field is placed into the next word. Fields are packed as they 
are encountered; the least significant bits of the structure word are filled first. 
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4.2 Register Conventions 


Strict conventions associate specific registers with specific operations inthe 
C environment. If you plan to interface an assembly language routine to a 
C program, it is important that you understand these register conventions. . 


4.2.1 Dedicated Registers 


The C environment reserves three registers. Do not modify these registers 
in any other manner than that described in Section 4.3, Function Call Con- 
ventions (page 4-8). 


ARO _ isthe frame pointer. It points to the current activation record (the be- 
ginning of the current frame). 


AR1 is the stack pointer. It points to the top of the runtime stack orto the 
word that follows the top of the stack. 


AR2_ isthe local variable pointer. It is used for calculating the address of 
local variables. 


4.2.2 Using Registers 
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The auxiliary registers, the accumulator, the T and P registers, and miscella- 
neous status registers can be used by assembly language functions; be 
sure to follow these rules: 


Ci Auxiliary Registers (ARP and ARO—AR7) 


m@ The ARP must contain a 1 when a function is entered and when a 
function returns. It may contain other values during function execu- 
tion. 


mM Registers ARO andARi1 maybe modified during function execution, 
but they must be restored. 


mM Registers AR2, AR3, AR4, and AR5 may be modified and do not 
need to be restored. 


M Registers AR6 and AR? are used for register variables. If they are 
modified, they must be saved and restored. 


Li Status Register 


m TheC compiler assumes thatthe PM status bits are always set to 0. 
If you change these bits, you must set them to 0 before returning 
from the function. 


m You can change the following status fields without restoring them: 
DP, C, FSM, HM, INTM, OV, OVM, SXM, TC, TXM, ARB, CNV, FO, 
and XF. 
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(i) Other Registers 


m@ You can use the accumulator without saving and restoring the origi- 
nal value. It is also used to return integers, pointers, and floating- 
point values. 


m Youcanuse the P and T registers without saving and restoring their 
Original values. 


4.2.3. Register Variables 


The C compiler uses up to two register variables within a function. You must 
declare the register variables in the argument list or in the first block of the 
function. Register declarations in nested blocks are treated as normal vari- 
ables. 


The compiler uses AR6 and AR7 for register variables: 
Ci ARG is assigned to the first register variable. 
Ca AR7 is assigned to the second variable. 


Note that the address of the variable is placed into the allocated register to 
simplify access. Thus, any type of variable may be used as a register vari- 
able. 


Setting up a register variable at run time requires approximately four instruc- 
tions per register variable. To use this feature efficiently, use register vari- 
ables only if the variable will be accessed more than twice. 


4-7 


atest aNtaeeTesadesasatartetatesenatecenatatatatecetanatetatatetetetetatecetetececatscetatecotatatetatssetatescotececatetetatecstocstonetetesatetotatetonetstonatacetetetetatacanecetotateiocatetetatetatatectotetestatecatatecetatesetatetstetatelonscetecsionatstenatesetetetanecatecstetetanecatocetatetenateteteteteteteratetatatatetatetetasetetatetetetetatstetetatetetetetatetetatet 


4.3. Function Call Conventions 


4.3.1 


The C compiler imposes a strict set of rules on function calls. Except for spe- 
cial runtime-support functions, any function that calls or is called by a C func- 
tion must follow these rules. Failure to adhere to these rules can disrupt the 
C environment and cause a program to fail. 


Passing Parameters to a Function 


If you pass parameters to a C function, you must follow these rules: 
La Push them on the runtime stack before you call the function. 


La Pass arguments in reverse order; thatis, push the first (leftmost) param- 
eter last, and push the last (rightmost) parameter first. This allows you 
to pass a variable number of parameters. 


La If an argument is a floating-point value, push the least significant word 
first. 


Lz Pass structures as multiples of words (they can be lengthened if neces- 
sary). 


4.3.2 Local Frame Generation 


When a function is called, the compiler builds a frame (or activation record) 
to store information on the runtime stack. The current function’s frame Is 
called the local frame. The C environment uses the local frame for saving 
information about the caller, passing arguments, and generating local vari- 
ables. Each time you call a function, a new frame is generated to store infor- 
mation about that function. When you return from a called function, the call- 
er’s frame is still on the stack so that you can continue to use that informa- 
tion. 


Register AR1 is the SP (stack pointer) and register ARO is the frame pointer 
(FP). The SP points to the next available word on the stack; the FP points 
to the local frame. 


The compiler performs the following tasks when it builds the local frame: 


1) Pops the return address (old PC value) from the TMS320C25 internal 
stack and pushes it on the runtime stack. 


2) Pushes the contents of the old FP onto the runtime stack and sets the 
new FP to the current SP. 


3) Increments the SP by the number of words needed to hold local vari- 
ables, plus one word at the beginning of the frame for temporary stor- 
age. (In the following code segment, the symbol s1zz represents the 
amount of this space.) 
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If the function uses AR6 and AR7 (as register variables), it pushes their 
contents onto the stack and then loads them with the addresses of ap- 
propriate local variables. 


Here is the TMS320C25 code that performs these tasks: 


POPD: *+ ; Pop return address 

SAR ARO, *+ ; Push on system stack 

SAR AR1, * ; Save old FP 

LARK ARO, SIZE 

LAR ARO, *0O+ ; FP = old SP, SP += SIZE 

SAR AR6, *+ ; Save AR6 

SAR AR7, *+ ; Save AR7 

There are several points to keep in mind about this method of frame genera- 
tion: 

La When a function is entered, the compiler assumes that the ARP points 


a 


to the stack pointer (AR1). 


There is no separate pointer to the argument list; the frame pointer is 
used with negative offsets to point to the arguments, and with positive 
offsets to point to local variables. 


The frame pointer (ARO) points to a single word, which is allocated be- 
fore the local variables. This word is used as atemporary memory loca- 
tion to allow register-to-register transfers and is essential to creating 
reentrant C functions. Note that this memory location can always be di- 
rectly accessed through ARO. 


The compiler uses AR2 to calculate the address of local variables. Gen- 
erally, the offset of the local variables is placed in AR2, and ARO is ada- 
ed to it. This value is not preserved across function calls. 


4.3.3 Function Termination 


When a function is terminated, it must perform the following tasks to restore 
the calling environment: 


1) 
2) 
3) 


Handle return values that will be passed to the caller. 
Restore AR6 and AR7 if it used them. 


Deallocate space used for local variables and temporary memory. (In 
the following code segment, the symbol s1zE represents the amount of 
this space.) 


Restore the old frame pointer. 
Push the return address onto the TMS320C25 stack and return to the 
caller. 
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Here is the TMS320C25 code that performs these tasks: 


LAR AR7, *- - 3 Restore AR7 

LAR AR6, *- ; Restore AR6 

SBRK SIZE : Deallocate frame 

LAR ARO, *- ; Restore FP 

PSHD * ; Put return address on internal stack 
RET ; Return to caller 

Note that - 

La Allreturn values are returned in the accumulator. Integers and pointers 


ia 


are returned (properly sign extended) in the 16 LSBs of the accumula- 
tor. Floating-point values use all 32 bits of the accumulator. 


Because the accumulator contains the return value, it must not be modi- 
fied by epilog code. 


Arguments are not popped off the stack by the called function; they must 
be popped by the caller. This allows you to pass any number of argu- 
menis to a function, and the function need not know how many were 
passed. | 


Upon return from a function, the ARP points to AR1. 


Structures cannot be returned from functions. 
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4.4 Interfacing C with Assembly Language 
There are three ways to use assembly language in conjunction with C code: 


Oo 


Ca 


a 


Use separate modules of assembled code and link them with compiled 
C modules (see Section 4.4.1). This is the most versatile method. 


Use inline assembly language, embedded directly in the C source (see 
Section 4.4.2, page 4—14). 


Modify the assembly language code that the compiler produces (see 
Section 4.4.3, page 4—15). 


4.4.1 Assembly Language Modules 


Interfacing with assembly language functions is straightforward If you follow 
the calling conventions defined in Section 4.3 and the register conventions 
defined in Section 4.2. C code can access variables and call functions de- 
fined in assembly language, and assembly code can access C variables and 
call C functions. 


Follow these guidelines to interface assembiy ianguage and C: 


1) 


2) 


6) 


All functions, whether they are written in C or assembly language, must 
follow the conventions outlined in Section 4.2. (page 4-6). 


You must preserve any dedicated registers modified by a function; dedi- 
cated registers include 


ARO (FP) AR6 
AR1 (SP) AR7 


Note that if SP is used normally, it does not need to be explicitly pre- 
served. In other words, the assembly function is free to use the stack as 
long as anything that is pushed is popped back off before the function 
returns (thus preserving SP). Any register that is not dedicated can be 
used freely without being saved. Upon return from the function, the ARP 
must be 1. 


Interrupt routines must save all the registers they use. (For more infor- 
mation about interrupt handling, see Section 4.5, page 4—16.) 


When calling a C function from assembly language, push any argu- 
ments onto the stack in reverse order. Pop them off after calling the func- 
tion. 


When calling C functions, remember that only the dedicated registers 
listed above are preserved. C functions can change the contents of any 
other register. 


Functions must return values correctly according to their C declara- 
tions. Integers and pointers are returned in the accumulator, and floa- 
ting-point values are returned on the stack. 
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7) Noassembly language module should use the .cinit section for any pur- 
pose other than autoinitialization of global variables. The C startup rou- 
tine in boot .asmassumes that the .cinit section consists entirely of ini- 
tialization tables. 





8) Thecompilerappends anunderscore(_ )tothe beginning of all identifi- 
ers. This means that you must prefix the name of all objects to be acces- 
sible from C with _ when writing assembly language. For example, a C 
object called xis called _« in assembly language. For identifiers to be 
used only in an assembly language module or modules, any name that 
does not begin with an underscore may be safely used without conflict- 
ing with a C identifier. 


9) Any object or function declared in assembly that is to be accessed or 
called from C must be declared with the .global assembler directive. 
This defines the symbol as external and allows the linker to resolve ref- 
erences to it. 


Similarly, to access a C function or object from assembly, declare the C 
object with .global, thus creating an undefined external reference that 
the linker will resolve. 


4.4.1.1 An Example of an Assembly Language Function 


The example in Figure 4—1 illustrates a C function called main, which calls 
an assembly language function called asmfunc. The asmfunc function takes 
its single argument, adds it to the C global variable called gvar, and returns 
the result. 


Figure 4—1. An Assembly Language Function 
(a) C program 


extern int asmfunc(); /* declare external asm function */ 
int. ovat; /* define global variable * / 


main () 


{ 


Lf = asmfunc(i); /* call function normally 
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Figure 4-1. An Assembly Language Function (Continued) 
(b) Assembly language program 


asmiunc: 
POPD * 4+ >; Move return address to C stack 
SAR ARO, *+ ; Save FP 
SAR ARI, * -; Save SP 
LARK ARO, 1 ; Size of frame 
LAR ARO, *O+, AR2 ; Set up FP and SP 





LDPK gvar ; Point. "Lo-gvar 

SSXM ; Set sign extension 
LAC gvar ; Load gvar 

LARK AR2, -3 >; Offset of argument 
MAR *Q+ ; Point to argument 

ADD *, ARQ ; Add arg to gvar 

SACL gvar ; Save in gvar 

LARP AR1 }. POp: -OEL prame 

SBRK 2 

LAR. ARO; = ; Restore frame pointer 
PSHD* ; “Move return: addr Fo -C25 stack 
RET 


Inthe C program in Figure 4—1, the externdeclaration of asmfunc is option- 
al, since the function returns an int. Like C functions, assembly functions 
need be declared only if they return noninteger values. In the assembly lan- 
guage code in Figure 4—1, note the underscores on all the C symbol names 
used in the assembly code. 


4.4.1.2 Defining Variables in Assembly Language 


Itis sometimes useful fora C program to access variables defined in assem- 
bly language. Accessing uninitialized variables from the .bss section Is 
straightforward: 


1) Use the .bss directive to define the variable. 

2) Use the .global directive to make the definition external. 

3) Remember to precede the name with an underscore. 

4) InC, declare the variable as extern, and access it normally. 

Figure 4—2 shows an example that accesses a variable defined in .bss. 
Figure 4-2. Accessing from C a Variable Defined in .bss 


(a) Assembly language program 


* Note the use of underscores in the following lines 


.bSS Meaty ; Define the variable 
.global Vas ; Declare it as external 
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Figure 4-2. Accessing from C a Variable Defined in .bss (Continued) 


(b) C program 


extern int var; /* External variable 


var = 1; /* Use the variable 





You may not always want a variable to be in the .bss section; for example, 
acommon situation is a lookup table defined in assembly that you don’t want 
to put in RAM. In this case, you must define a pointer to the object and ac- 
cess it indirectly from C. 


The first step is to define the object; it is helpful (but not necessary) to put 
itin its own initialized section. Declare a global label that points to the begin- 
ning of the object, and then the object can be linked anywhere into the 
memory space. To access it in C, you must declare an additional C variable 
to point to the object. Initialize the pointer with the assembly language label 
declared for the object; remember to remove the underscore. 


Figure 4-3 shows an example that accesses a variable that is not defined 
in .bss. 


Figure 4-3. Accessing from C a Variable not Defined in .bss 


4.4.2 
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(a) Assembly language program 


-global _sine + Declare variable as external 
.sect “sine tab” ; Make a separate section 
_sine: ; The table starts here 


-float 0.0 
-float 0.015987 
-float 0.022145 





(b) C program 


extern float sine[]; /* This is the object */ 


float *sine_ p = sine; /* Declare pointer to point to it */ 
f = sine p[4]; /* Access sine as normal array x / 





Inline Assembly Language 


Within a C program, you can use the asm statement to inject a single line 
of assembly language into the assembly language file that the compiler 
creates. Aseries of asm statements places sequential lines of assembly lan- 
guage into the compiler output with no intervening code. 
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The asm statementis also useful for inserting comments in the compiler out- 


put; simply start the assembly code string with an asterisk (*) as shown be- 
low: 


asm(”**** this is an assembly language comment”); 


4.4.3. Modifying Compiler Output 


You can inspect and change the assembly language output thatthe compiler 
produces by compiling the source and then editing the output file before as- 
sembling it. The warnings in Section 4.4.2 about disrupting the C environ- 
ment also apply to modification of compiler output. 
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4.5 Interrupt Handling 


4-16 


Interrupts can be handled directly with C functions by using the following re- 
served function names, which are associated with the indicated interrupt: 


c_int0 system reset interrupt 
c_intt external interrupt 0 

c_int2 external interrupt 1 

c_int3 external interrupt 2 

c_int4 internal timer interrupt 
c_int5 — serial port receive interrupt 
c_int6 — serial port send interrupt 


Using one of these function names defines an interrupt routine for the appro- 
priate interrupt. When the compiler encounters one of these function 
names, it generates code that allows the function to be activated from an 
interrupt trap. Note that this method provides more functionality than the 
standard C signal mechanism. This does not prevent implementation of the 
signal function, but it does allow these functions to be written entirely in C. 


When an interrupt handling function is entered, the runtime-support function 
ISSSAVE is called to save the complete context of the interrupted function. 
All registers are saved. Upon return from the interrupt handling function, the 
runtime-support function IS$REST is called to restore the environment and 
return to the interrupted function. 


An interrupt routine may perform any task performed by any other function, 
including accessing global variables, allocating local variables, and calling 
other functions. | 


When you write interrupt routines, keep the following points in mind: 


La tis your responsibility to handle any special masking of interrupts (via 
the IMR register). You can use inline assembly to enable or disable the 
interrupts and modify the IMR register without corrupting the C environ- 
ment. 


La An interrupt handling routine cannot have arguments. If any are de- 
clared, they are ignored. 


La An interrupt handling routine can be called by normal C code, but it is 
inefficient to do this because all the registers are saved. 


La An interrupt handling routine can handle a single interrupt or multiple 

interrupts. The compiler does not generate code that is specific to a cer- 

tain interrupt, except for c_intO, which is the system reset interrupt. 

When you enter this routine, you cannot assume that the runtime stack 

is set up; therefore, you cannot allocate local variables, and you cannot 
save any information on the runtime stack. 
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[4 To associate an interrupt routine with an interrupt, a branch must be 
placed in the appropriate interrupt vector. The assembler and linker can 
easily accomplish this by creating a simple table of branch instructions. 


[i In assembly language, remember to precede the symbol name with an 
underscore. For example, refer to c_intO aS_c_into. 
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4.6 


integer Expression Analysis 


Most integer expressions are analyzed in the 16 LSBs of the accumulator 
orinthe Por T registers. TMS320C25 C follows Kernighan and Ritchie stan- 
dard precedence rules for evaluating expressions; however, the order of ex- 
pression analysis is based on the complexity of the operands. (Note that this 


does not apply to operators such as the comma, &&, or ||, which specify a 


particular order of analysis.) The following rules determine which portion of 
an expression is evaluated first: 


1) If the expression contains a division or modulus operation, the right- 
hand side of the expression is evaluated first. otherwise, 


2) If either operand contains a function call, the function call is evaluated 
first. otherwise, 


3) Ifeither operand contains a multiplication expression, the multiplication 
is evaluated first. otherwise, 


4) Ifrules 1—3 do notapply, the operand that appears to be more complex 
is evaluated first. (Complexity is based on the number and types of op- 
erations.) 


4.6.1 Arithmetic Overflow and Underflow 


The TMS320C25 performs 32-bit math with 16-bit values; thus, arithmetic 

overflow and underflow cannot be handled in a predictable manner. 

If code depends on a particular type of overflow/underflow handling, there. 
is no guarantee that this code will execute correctly. Generally, it is a good 

practice to avoid such code because it is not portable. 


4.6.2 Integer Division and Modulus 
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The TMS320C25 does not directly support integer division, so all division 
and modulus operations are performed through calls to runtime-support 
routines. These functions push the right-hand portion (divisor) of the opera- 
tion onto the stack, and then place the left-hand portion (dividend) into the 
16 LSBs of the accumulator. The function places the result in the accumula- 
tor. 
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4.7 Floating-Point Expression Analysis 


The TMS320C25 C compiler represents floating-point values as IEEE sing- 
le-precision numbers. Both single-precision and double-precision floating- 
point numbers are represented as 32-bit values; there is no difference be- 
tween the two formats. 


The TMS320C25 floating-pointlibrary, £1ib.1ib, contains acustom-coded 
set of floating-point math functions that support 


Ci Addition, subtraction, multiplication, and division 
[i Comparisons (>, <, >=, <=, ==, !=) 


[i Conversions from integer to floating point and floating point to integer, 
both signed and unsigned 


Ck Standard error handling 


These functions do not follow standard C calling conventions. Instead, the 
compiler pushes the arguments onio the runtime siack arid generates acai 
to a floating-point function. The function pops the arguments, performs the 
operation, and pushes the result onto the stack. 


Some floating-point functions expect integer arguments or return integer 
values. For floating-point functions, all integers are passed and returned in 
the 16 LSBs of the accumulator. 


The compiler does not recognize the internal format of floating-point num- 
bers; the only restriction is the data size of the number. This allows you to 
customize a floating-point package for a particular environment. 
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4.8 System Initialization 


Before you can run a C program, the C runtime environment must be 
created. This task is performed by the C boot routine, which is a function 
called c_int0. The runtime-support source library contains the source to this 
routine in a module called boot .asm. 


The c_intO function can be called by reset hardware to begin running the 
system. The function is in the runtime-support library (rts.1ib) and must 
be combined with the C object modules at link time. This occurs by default 
when you use the —-c or -cr linker option and include rts.1ib as a linker in- 
put file. When you use —c or -cr, the linker sets the entry point in the execut- 
able output module to the symbol_c_int0. The C boot routine performs three 
tasks: 


La It reserves space in .bss for the runtime stack and sets up the initial 
stack pointer and frame pointer. 


Lk It autoinitializes global variables by copying the data from the initializa- 
tion tables in .cinit to the storage allocated for the variables in .bss. 


Note that in the RAM autoinitialization model, a loader performs this 
step before the program runs (it is not performed by the boot routine). 


L4 It calls the function main to begin running the C program. 


You can replace or modify the C boot routine, if necessary, to meet the par- 
ticular requirements of your system. However, you must be sure to perform 
the preceding three steps correctly to initialize the C environment properly. 


4.8.1 Runtime Stack 
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The runtime stack is allocated in a single contiguous block of memory and 
grows up from low addresses to higher addresses. Register AR1 usually 
points to the next available word in the stack (top of the stack plus one word). 
The compiler can use this word as a temporary memory location, so it must 
be saved by interrupt routines. 


The code doesn’t check to see if the runtime stack overflows. Stack overflow 
occurs when the stack grows beyond the limits of the memory space that 
was allocated for it. Be sure to allocate adequate memory for the stack. 


The stack is allocated by the runtime-support module boot .asmas a static 
array named SYS_STACK. (boot .asmis amember of the rts. src library.) 
set the size of this array to the size required for the stack. Other methods 
of stack allocation can be used, but you must then rewrite the c_intO boot 
function to comprehend the new configuration. 
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4.8.2 Autoinitialization 


Before program execution, any global variables declared as preinitialized 
must be initialized by the boot function. The compiler builds tables that con- 
tain data for initializing global and static variables in a .cinit section in each 
file. Allcompiled modules contain these initialization tables. The linker com- 
bines them into a single table which is then used to initialize all the system 
variables. (Do not place any other data in the .cinit section; this corrupts the 
tables.) 


The tables in the .cinit section consist of initialization records with varying 
sizes. Each initialization record has the following format: 


Offset Contents 
Word 0 Length of initialization data (in words) 
Word 1 Address of variable to be initialized 
Word 2...n Data to be copied into the variable 


1) The first field (word 0) is the size in words of the initialization data for 
the variable. 


2) The second field (word 1) is the starting address of the area in the .bss 
section into which the data must be copied. 


3) The third field (words 2 through n) contains the data that is copied into 
the variable to initialize it. 


The .cinit section contains an initialization record for each variable that must 
be initialized. For example, suppose two initialized variables are defined in 
C as follows: 


ant. a. 5239 
LAC a{S] = {1, 2, 3, 4, 5 };3 


The initialization tables would appear as follows: 


-sect Clan’ ; Initialization section 
* Initialization record for variable i 
.word 1 ; Length of data (1 word) 
.word ode ; Address in .bss 
.word 23 ’ Data: £O-a2naeilalize 3 
* Initialization record for variable a 
.word 5 ; Length of data (5 words) 
.word _a ; Address in .bss 
.word Le Zp papo ; Data to initialize a 


The .cinit section contains only initialization tables in this format. When in- 
terfacing assembly language modules, do not use the .cinit section for any 
other use. 
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When you link a program with the —-c or -cr option, the linker links the .cinit 
sections from all the C modules together and appends a null word to the 
end of the entire section. This appears as a record with a size field of 0 and 
marks the end of the initialization tables. 


4.8.2.1 ROM Initialization Model 


The ROM model is the default model for autoinitialization. To use the ROM 
model, invoke the linker with the —c option. 


Under this method, the .cinit section is loaded into memory (possibly ROM) 
along with all the other sections, and global variables are initialized at run 
time. The linker defines a special symbol called cinit that points to the be- 
ginning of the tables in memory. When the program begins running, the C 
boot routine copies data from the tables (pointed to by cinit) into the speci- 
fied variables in .bss. This allows initialization data to be stored in ROM and 
then copied to RAM each time the program is started. 


4.8.2.2 RAM Initialization Model 
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The RAM model, specified with the -cr linker option, allows variables to be 
initialized at load time instead of at runtime. This can enhance perform- 
ance by reducing boot time and can save the memory used by the initializa- 
tion tables. The RAM option requires the use of a smart loader to perform 
the initialization as it copies the program from the object file into memory. 


In the RAM model, the linker marks the .cinit section with a special attribute. 
This means thatthe section is not loaded into memory and does not occupy 
space in the memory map. The symbol cinit is set to —1 to indicate to the 
C boot routine that the initialization tables are not present in memory; ac- 
cordingly, no runtime initialization is performed at boot time. 


Instead, when the program is loaded into memory, the loader must detect 


the presence of the .cinit section and its special attribute. Instead of loading 
the section into memory, the loader uses the initialization tables directly from 
the object file to initialize the variables in .bss. To use the RAM model, the 
loader must understand the format of the initialization tables so that it can 
use them. 
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Some of the tasks that a C program must perform (such as memory 
allocation, string conversion, and string searches) are not part of the C 
language. The runtime-support functions, which are included with the C 
compiler, are standard functions that perform these tasks. The runtime- 
support library rts .1ib contains the object code for each of the functions 
described in this chapter; the library rts. src contains the source to these 
functions as well as to other functions and routines. if you use any of ihe 
runtime-support functions, be sure to include rts.1ibas an input file when 
you link your C program. 
f 


This chapter is divided into three parts: 
Ly Part 1 describes header files and discusses their functions. 


Li Part 2 summarizes the runtime-support functions according to 
category. 


La Part 3 is an alphabetical reference. 


You can find these topics on the following pages: 


Section | Page 
Det ‘GaGer MilGS: 4.2 ccaapercin ve aetna ea beeeneeaoeis andes eee 5-2 
5.2 Summary of Runtime-Support Functions and Macros ......... 5-8 
5.3: -PUNCHONS RGICIENCe: s4a cco eciis sau deeencereteddavaeotiaenes 5-14 
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5.1 Header Files 


Each runtime-support function is declared in a header file. Each header file 
declares 


Ly Aset of related functions (or macros), 

Lua Any types that you need to use the functions, and 

La Any macros that you need to use the functions. 

The header files that declare the runtime-support functions are: 


assert.h limits.h stddef.h 
ctype.h math.h stdlib.h 
errno.h stdarg.h string.h 
float.h 


To use a runtime-support function, you must first use the #include 
preprocessor directive to include the header file that declares the function. 
For example, the isdigit function is declared by the ct ype.h header. Before 
you can use the isdigit function, you must first include the ctype .h file 


#include <ctype.h> 


val = isdigit (num) 
You can include headers in any order. You must include a header before you 
reference any of the functions or objects that it declares. 


Sections 5.1.1 through 5.1.8 describe the header files included with the 
TMS320C25 C compiler. Section 5.2, page 5-8, lists the functions that 
these headers declare. 


5.1.1 Diagnostic Messages (assert .h) 


The assert .h header defines the assert macro, which provides a standard 
method for allowing programs to create diagnostic failure messages at 
runtime. The assert macro tests a runtime expression. 


Li If the expression is true, the program continues running. 


La If the expression is false, a message is printed that contains the 
expression, the source filename, and the line number of the statement 
that contains the expression; then, the program terminates (via the 
abort function). 


The assert .h header refers to another macro named NDEBUG (assert .h 
does not define NDEBUG — you must define it). If NDEBUG is defined as 
a macro name when you include assert .h, then the assert macro is turned 
off and has no effect. 
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5.1.2 Character Typing and Conversion (ctype.h) 


The ctype.h header declares functions and defines macros that test or 
convert ASCII characters: 


La The character-testing functions have names with the format isxxxx (for 
example, isdigit). These functions return true (1) or false (0). 


La The character-conversion functions have names in the format toxxxx 
(for example, toupper). They convert a character to lowercase, 
uppercase, or ASCII, and return the converted character. 


The ctype.h header also defines macro definitions that perform these 
same operations. The typing functions expand to a lookup operation in an 
array of flags (this array is defined in ctype.h). The macros have the same 
names as the corresponding functions, prefixed with an underscore (for 


example, _/sascil). 
5.1.5 Limits (float. and limits.h) 


The float .h and limits.h headers define macros that expand to useful 
limits and parameters of numeric representations. Table 5—1 and Table 5-2 
list these macros and the limits they are associated with. 
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Table 5-1. Macros That Supply Limits for Characters and Integers 





Macro Value Description 

CHAR_BIT 16 Maximum number of bits for the 
smallest object that is not a bit field 

SCHAR_MIN —32768 Minimum value for a signed char 

SCHAR_MAX 32767 Maximum value for a signed char 

UCHAR_MAX 65535 Maximum value for an unsigned char 


CHAR_MIN SCHAR_MIN Minimum value for a char 
CHAR_MAX SCHAR_MAX Maximum value for a char 


SHRT_MIN —32768 Minimum value for a short int 
SHRT_MAX 32767 Maximum value for a short int 
USHRT_MAX 65535 Maximum value for an unsigned short int 
INT_MIN —32768 Minimum value for an int 

INT_MAX 32767 Maximum value for an int 

UINT_MAX 65535 : Maximum value for an unsigned int 
LONG_MIN —32767 Minimum value for a long int 
LONG_MAX 32767 Maximum value for a long int 
ULONG_MAX 65535 Maximum value for an unsigned long int 
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Table 5-2. Macros That Supply Limits for Floating-Point Numbers 





Macro Value 
FLT RADIX 2 
FLT ROUNDS 1 


FLT_DIG. 6 
DBL_DIG 
LDBL_DIG 


FLT_MANT_DIG 24 
DBL_MANT_DIG 
LDBL_DIG 


FLT_MIN_EXP —125 
DBL_MIN_EXP 
LDBL_MIN_EXP 


rar re 


FLI_MAX_EAP 
DBL_MAX_EXP 
LDBL_MAX_EXP 


FLT EPSILON 1.19209290E-07F 
DBL_EPSILON 
LDBL_EPSILON 


FLT_MIN 1.17549435E-38F 
DBL_MIN 
LDBL_MIN 


FLT MAX 3.40282347E+38F 
DBL_MAX 
LDBL_MAX 


FLT_MIN_10_EXP —37 
DBL_MIN_10_EXP 
LDBL_MIN_10_EXP 


FLT _MAX_10_EXP 38 
DBL_MAX_10_EXP 
LDBL_MAX_10_EXP 


Key to prefixes: 

FLT applies to type float 

DBL___ applies to type double 
LDBL_ applies to type long double 


aoe 


5.1.4 Floating-Point Math (math .h) 


Description 


Base or radix of exponent representation 


Rounding mode for floating-point addition 
(rounds to nearest integer) 


Number of decimal digits of precision for a 
float, double, or long double 


Number of base-FLT_RADIX digits in the 
mantissa of a float, double, or long double 


Minimum negative integer such that FLT_RA- 
DIX raised to that power minus 1 is a normal- 
ized float, double, or long double 


BOA em rt mem $ om ae ok te ha mir 
Maximum integer sucn ihat FLT_RADIX 


raised to that power minus 1 is arepresentive 
finite float, double, or long double 
Minimum positive float, double, or long double 
number x such that 1.0+ x#1.0 


Minimum positive float, double, or long double 


Maximum float, double, or long double 


Minimum negative integer such that 10 raised 
to that power is in the range of normalized 
floats, doubles, or long doubles 


Maximum integers such that 10 raised to that 
power is in the range of representable finite 
floats, doubles, or long doubles 


The math.h header defines several trigonometric, exponential, and 
logarithmic functions. These math functions expect floating-point 
arguments of type double and return floating-point values of type double. 
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(In TMS320C25 C, a double is equivalent to a float and is actually a single- 
precision number.) 

Most of the math functions expect arguments to be within a certain range. 
The math.h header also defines three macros that can be used with the 
math functions for reporting range errors: 


La EDOM 
Lk ERANGE 
Ly ~=HUGE_VAL 


If the value of an argument is outside the expected range, a domain error 
occurs, and the errno macro is set to the value of the EDOM macro. If aresult 
cannot be represented (usually because it’s too large), or if a result over- 
flows, a function returns the value of the HUGE_VAL macro, and the errno 
macro is set to the value of the ERANGE macro. 


lf the result of a floating-point math function cannot be represented as a floa- 
ting-point value, a range error occurs. 


5.1.5 Variable Arguments (stdarg.h) 


A function can be called with a variable number of arguments with different 
types. The stdarg.h header declares 


Li A type, va_list, and 
La Three macros, va_start, va_arg, and va_end. 


A variable-argument function can use the objects declared by stdarg.h to 
advance through a list of arguments when the number and types of 
arguments that are passed to it may vary. 


The va_list type is an array type that can hold information for the macros. 


5.1.6 Standard Definitions (stddef .h) 
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The stddef.h header defines two types and three macros. The types 
include 


La ptrdiff_t is asigned integer that is the result type from subtracting two 
pointers . 

Ly size_t is an unsigned integer that is the result type of the sizeof 
operator. 

The macros include 

Ly NULL, which expands to a null pointer constant 

lL offsetof(type, identifier), which expands to an integer that has type 


size_t. The result is the value of an offset in bytes to a structure member 
(identifier) from the beginning of its structure (type). 


La errno, which expands to the variable errno. This macro is used to re- 
port errors from runtime-support functions. 
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These types and macros are used by several of the runtime-support 
functions. 


5.1.7 General Utilities (stdlib.h) 


The stdlib.h header declares several macros, as well as two types. The 
macros include 


a 
Ch 
Ld 


EXIT_FAILURE 
EXIT SUCCESS, and 
RAND_MAX. 


The stdlib.h header declares several kinds of functions: 


Ci 


a 


Memory management functions that allow you to allocate and 
deallocate packets of memory. The amount of memory that these 
functions can use is defined by the macro memory_size in the runtime- 
support module memory. c. (This module is defined in the file rts. sxc.) 
By default, the amount of memory available for aliocation is 1000 words. 
You can change this amount by modifying the memory_size macro and 
recompiling memory.c. 


String-conversion functions that convert strings to numeric 
representations. 


Searching and sorting functions that allow you to search and sort 
arrays. 


Sequence-generation functions that allow you to generate a pseudo- 
random sequence and allow you to choose a starting point for a 
sequence. 


Function-exit functions that allow you to terminate functions normally 
or abnormally. 


5.1.8 String Functions (string.h) 


The string.h header declares functions that allow you to perform the 
following tasks with character arrays (strings): 


Cd 
Cd 
Ld 
Cd 
Ch 


Move or copy entire strings or portions of strings, 
Concatenate strings, 

Compare strings, 

search strings for characters or other strings, and 
Find the length of a string. 


When you use functions that move or copy strings, be sure that the 
destination is large enough to contain the result. 
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Table 5—3. Error Message Macro 
(Header File: assert .h) 


Macro and Syntax Description 


void assert (expression) Inserts diagnostic messages into programs 
int expression; 


Table 5-4. Character Typing and Conversion Functions 


(Header File: ct ype.h) 


Function and Syntax Description 

int isalnum (c) Identifies alphanumeric-ASCIl characters 
char c: 

int isalpha (c) | Identifies alphabetic-ASCII characters 
char c: 

int isascii (c) Identifies ASCII characters 
char c: 

int isentrl (c) Identifies control characters 
char c: 

int isdigit(c) Identifies numeric characters 
char c: 

int rt isgraph (c) | Identifies any printing character except a space 
cnar C: 

int i islower (c) Identifies lowercase alphabetic ASCII characters 
cnar Ce. 

int isprint (c) Identifies printable ASCII characters (including 
char c: spaces) 
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Character Typings and Conversion Functions (continued) 


Function and Syntax 


int ispunct (c) 
char se. 


int isspace (c) 
char c: 

int isupper (c) 
char c: 


int isxdigit (c) 
char -<@x 


char toascii (c) 
Char: cx 


char tolower (c) 
char: ¢é 


char toupper (c) 
char c¢: 


Description 
Identifies ASCII punctuation characters 


Identifies ASCII spacebar, tab (horizontal or _ 
vertical), carriage return, formfeed, and newline 
characters 


Identifies uppercase ASCIl alphabetic characters 


Identifies hexadecimal digits 
Masks c into a 7-bit ASCII character 
Converts an uppercase argument to lowercase 


Converts a lowercase argument to uppercase 


Table 5—5. Floating-Point Math Functions 


Function and Syntax 


double acos (x) 
double x; 


double asin (x) 
double x; 


double atan (x) 
double x; 


double atan2 (y,x) 
double y,x; 


double ceil (x) 
double x; 


double cos (x) 
double x; 


double cosh (x) 
double x; 


double exp (xX) 
double x; 


double fabs (x) 
double x; 


double floor (x) 
double x; 


double fmod (x, y) 
double x, y; 


(Header File: math.h) 


Description 
Returns the arc cosine of a floating-point value 


Returns the arc sine of a floating-point value 
Returns the arc tangent of a floating-point value 
Returns the inverse tangent of y/x 

Returns the smallest integer greater than or equal 
to x 

Returns the cosine of a floating-point value 
Returns the hyperbolic cosine of a floating-point 
value 

Returns the exponential function of a real number 
Returns the absolute value of a floating-point value 


Returns the largest integer less than or equal to x 


Returns the floating-point remainder of x/y 
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Floating-Point Math Functions (continued) 


Function and Syntax 


double frexp (value,exp) 
double value; 


int *exp; 
double ldexp (x, exp) 
double x; 
int exp; 
double log (x) 
double x; 
double log10 (x) 
double x; 
doublemod£ (value, iptr) 
double value; 
int *IDtEL; 
double pow (x, y) 
double x, y; 
double Sin (x) 
double x; 
double sinh (x) 


double x; 


double sqrt (x) 
double x; 
double tan (x) 


double x; 


double tanh (x) 
double x; 


Table 5-6. Variable Argument Macros 


(Header File: 


Function and Syntax 


type va_arg (ap, type) 


va_list ap; 


void va_end (ap) 
va_list ap; 


void va_start(ap, parmN) 
va_list ap; 


Description 


Breaks a floating-point value into a normalized 
fraction and an integer power of 2 


Multiplies a floating-point number by an integer 
power of 2 


Returns the natural logarithm of a real number 
Returns the base-10 logarithm of a real number 


Breaks a floating-point number into a signed 
integer and a signed fraction 


Returns x raised to the power y 
Returns the sine of a floating-point value 


Returns the hyperbolic sine of a floating-point value 


Returns the nonnegative square root of a real 
number 


Returns the tangent of a floating-point value 


Returns the hyperbolic tangent of a floating-point 
value 


stdarg.h) 


Description 


Accesses the next argument of type typeina 
variable-argument list 


Resets the calling mechanism after using va_arg 


Initializes ap to point to the first operand in the 
variable-argument list 
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Table 5—7. General Utilities 





(Header File: stdlib.h) 


Function and Syntax Description 

int abs (j) Returns the absolute value of an integer 
tnt oy 

void abort () Terminates a program abnormally 

void atexit (fun) Registers the function pointed to by fun, to be 
void (*fun) (); called without arguments at normal program 

termination 

int atof (nptr) Converts an ASCIl string to a floating-point value 
char *nptr; 

int atoi (nptr) Converts an ASCII string to an integer value 
char *nptr; 

long int atol (nptr) Converts an ASCII string to a long integer 
char *nptxr; 


a 
void *bsearch (key, base, nmemb, size, compar) 


void *key, *base; Searches through an array of nmemb objects for a 
size_t nmemb, size; member that matches the object that key points to 
int (*compar) (); 

void *calloc (nmemb, size) Allocates and clears memory for nmemb objects 
size_t nmemb, size 

void exit (status) Terminates a program normally 
int status; 

void free (ptr) Deallocates memory space allocated by malloc, 
void *ptr; calloc, or realloc 

int labs (j) Returns the absolute value of an integer 

Ine. 33 

int ltoa (n, buffer) Converts a long integer to the equivalent ASCII 
long n; string 
char *buffer; 

void *malloc (size) Allocates memory for an object of size bytes 
size t size 

void *minit () Resets the memory pool used for dynamic 

allocation 
char *movmem (src,dest, count) Moves count bytes from one address to another 


char *src, *dest; 
int count; 


void qsort (base, nmemb, size, compar) 


void *base; Sorts an array of nmemb members; base points 
size t nmemb, size; to the first member of the unsorted array and size 
int (*compar) (); specifies the size of each member 
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General Utilities (continued) 


Function and Syntax 


int rand () 


void*realloc (ptr, 
void yale eae: 
Size t size; 


size) 


void Srand (seed) 
unsigned int seed; 


double strtod (nptr, endptr) 
char *nptr, **endptr; 

long int strtol (nptr, endptr, 

base) 


char *nptxr,**endptr; 
int base; 


unsigned longint strtoul 
char *nptr, **endptr; 
int base; 


Table 5-8. String Functions 


Description 


Returns a sequence of pseudo-random integers in 
the range 0 to RAND_ MAX 


Changes the size of an allocated memory space 


Sets the value of seed so that a subsequent call to 
rand produces a new sequence of pseudo-random 
numbers 


Converts an ASCII string to a floating-point value 


Converts an ASCIl string to a long integer 


Converts an ASCII string to a long integer 


(Header File: string.h) 


Function and Syntax 


void *memchr(s, c, n) 
void *s; 
ane Cc; 
S126" 20... 


int memcmp (sl, 
void SSL, EZ 
Size tn; 


S250) 


void *memcpy (sl, s2, n) 
void *S1,. *s23 
Size t n; 

void *memmove (sl, s2, n) 
void *S1).*S2> 


Size. t n; 


void *memset (s, c, n) 
void ¥*s; 
pees Cc 


Si.2e6.°0. ny 


char *streat (sl, s2) 
cnar *sl, *s2; 
char *strehr (s, c) 
char *s; 
int c; 
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Description 


Finds the first occurrence of c in the first n char- 
acters of an object | 


Compares the first n characters of object1 to ob- 
ject2 


Copies n characters from object to object2 


Moves n characters from object1 to object2 


Copies the value of c into the first n characters of 
an object 


Appends string1 to the end of string2 


Finds the first occurrence of a character ina string 
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int stremp (sl, s2) Compares strings and returns one of the following 
char *sl, *s2; values: <0 ifs1 is less than s2; =0 if s1 is equal 
is greater than s2 to s2 >0 if s1 is greater than s2 
int *strceoll (sl, s2) Compares strings and returns one of the following 
char *sl, *s2; values, depending on the locale in the program: <0 


if s1 is less than s2; =O if s1 is equal to s2; >0 if 
s1 is greater than s2 


char *strepy (sl, s2) Copies a string to a new location 
char *sl, *s2; 

size_t strespn (sl, s2) Returns the length of the initial segment of string1 
char *sl, *s1l; that is entirely made up of characters that are not 

in string2 

char *strerror (errnum) Maps the error number in errnum to an error mes- 
int errnum; sage string 

size t strlen (s) Returns the length of a string 


char *s; 


char *strneat (sl, s2, n) Appends up to n characters from string1 to string2 
char *sl, *Ss2; 
Size t n; 


char *strnemp (sl, s2, n) Compares up to n characters in two strings 
char eS le S25 
size t n; 


char *strnepy (sl, s2, n) Copies up to n characters of a string to a new loca- 
char *s1, *s2; tion 
Size t n; 

char *strpbrk (sl, s2) Locates the first occurrence in string1 of any char- 
char *sl, *s2; | acter from string2 

char *strrehr (s, c) Finds the last occurrence of a character in a string 
char *s; 
int: “Cc; 

size t  strspn (sl, s2) Returns the length of the initial segment of string1 
char *sl, *s2; which is entirely made up of characters from 

string2 

char *strstr (sl, s2) Finds the first occurrence of a string in another 
char *sl, *s2; string 

char *strtok (sl, s2) Breaks a string into a series of tokens, each delim- 
char *sl, *s2; ited by a character from a second string 
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5.3 Functions Reference 
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The remainder of this chapter is a reference. Generally, the functions are 
organized alphabetically, one function per page; however, related functions 
(such as isalpha and isascii) are presented together on one page. Here’s 
an alphabetical table of contents for the functions reference: 
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abort Abnormal Termination 
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Syntax #include <stdlib.h> 


void abort () 
Definedin exit.cinrts.sre 
Description The abort function usually terminates a program with an error code. The 


TMS320C30 implementation of the abort function calls the exit function with 
a value of 0, and is defined as follows: 


void abort () 


{ 
exit (0); 
} 


This makes the abort function functionally equivalent to the exit function. 
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Syntax #include <stdlib.h> 
int abs(j) 
cnt ° 5 
long int labs (k) 
long int’ k; 
Definedin§ abs.cinrts.sre 


Absolute Value of an Integer abs/labs 
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Description The C compiler supports two functions that return the absolute value of an 


integer: 


Lk The abs function returns the absolute value of an integer, 3. 


C4 The labs function returns the absolute value of a long integer, k. 


Because int and long int are functionally equivalent types in TMS320C30 
C, the abs and labs functions are also functionally equivalent. 


acos Arc Cosine 
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Syntax 


Defined in 


Description 


Example 
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#include <math.h> 


double acos (x) 
double x; 


asin.objinrts.lib 


The acos function returns the arc cosine of a floating-point argument, x. Ar- 
gument x must be in the range [-1,1]. The return value is an angle in the 
range [0,7] radians. 


double realval, radians; 
realval = 1.0; 


radians = acos(realval) ; 
return (radians) /* acos returns p/2 x / 


Runtime-Support Functions 
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Defined in 


Description 


Example 
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#include <math.h> 


double asin (x) 
double x; 


asin.objinrts.lib 


The asin function returns the arc sine of a floating-point argument, x. Argu- 
ment x must be in the range [—1,1]. The return value is an angle in the range 


[—10/2, 10/2] radians. 


double realval, radians; 


have 


radians = asin(realval) ; /* asin returns 1/2 * / 


realval 


assert /nsert Diagnostic Information Macro 
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Syntax 


Defined in 


Description 


Example 
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#include <assert.h> 


void assert (expression) 
int expression; 


assert.haS macros 


The assert macro tests an expression; depending on the value of the ex- 
pression, assert either aborts execution and issues a message or continues 
execution. This macro is useful for debugging. 


La If expression is false, the assert macro writes information about the 
particular call that failed to the standard output and then aborts 
execution. 


La If expression is true, the assert macro does nothing. 


The header file that declares the assert macro refers to another macro, 
NDEBUG. If you have defined NDEBUG as a macro name when the 
assert .h header is included in the source file, then the assert macro is de- 
fined as 


#define assert (ignore) 


If NDEBUG is not defined when assert . his included, then the assert macro 
is defined as 


#define assert(expr) \ 
if (!(expr)) { 
printf (“Assertion failed, (expr), file %s, 
line d\n”, _ FILE _LINE__) 
abort (); } 


In this example, an integer i is divided by another integer j. Because divid- 
ing by 0 is an illegal operation, the example uses the assert macro to test 
3 before the division. If j3=0, assert issues a message and aborts the pro- 
gram. 

int Lae yy 

assert (j); 

q = i/j; 
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Syntax 


Defined in 


Description 


Example 


Arc Tangent ata 


#include <math.h> 


double atan (x) 
double x; 


atan.objinrts.lib 


The atan function returns the arc tangent of a floating-point argument, x. 
The return value is an angle in the range [—1/2,7t/2] radians. 


double realval, radians; 


realval 0:. 07 
radians = atan(realval); /* return value = 0 */ 
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Syntax #include <math.h> 
double atan2(y, x) 
° 
double ‘vy x: 


Definedin  atan.obj inrts.lib 


Description The atan2 function returns the inverse tangent of y/x. The function uses the 
signs of the arguments to determine the quadrant of the return value. Both 
arguments cannot be 0. The return value is an angle in the range [—1,7] 
radians. 


Example double rvalu, rvalv; 
double radians; 


rvalu S008 
ie- Oe 
radians = atan2(rvalr, rvalu); /* return value = 0 “7. 


rvalv 
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Syntax 


Defined in 


Description 


Exit Without Arguments atexit 
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#include <stdlib.h> 


void atexit (fun) 
void (*fun) (); 


exit.cinrts.sre 


The atexit function registers the function that is pointed to by fun, to be 
called without arguments at normal program termination. Up to 32 functions 
can be registered. 


When the program exits through a call to the exit function, the functions that 
were registered are called, without arguments, in reverse order of their 
registration. 
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-atof/atoi/atol ASCII to Number 
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Syntax #include <stdlib.h> 


double atof (nptr) 
char *nptr; 

int atoi (nptr) 
char *nptr; 

long int atol (nptr) 
char *nptr; 


Description Three functions convert ASCII strings to numeric representations: 


[3 The atof function converts a string to a ane ed value. The string 
must have the following format: | 


[space] [sign] digits [.digits] [e/E [sign] integer] 


C4 The atoi function converts a string to an integer. The string must have 
the following format: 


[space] [sign] digits 


C4 The atol function converts a string to a long integer. The string must 
have the following format: 


[space] [sign] digits 


The space is indicated by a spacebar, horizontal or vertical tab, carriage re- 
turn, form feed, or newline. Following the space is an optional sign, and then 
digits that represent the integer portion of the number. The fractional part 
of the number follows, then the exponent, including an optional sign. 


The first unrecognized character terminates the string. 


Because int and /ong int are functionally equivalent in TMS320C25 C, the 
atoi and atol functions are also functionally equivalent. 


The functions do not handle any overflow resulting from the conversion. 
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Syntax 


Defined in 


Description 


Array Search bsearch 
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#include <stdlib.h> 


void *bsearch(key, base, nmemb, size, compar) 
void *key, *base; 
size t nmemb, size; 
int (*compar) (); 


bsearch.cinrts.srcec 


The bsearch function searches through an array of nmemb objects for a 
member that matches the object that key points to. Argument base points 
to the first member in the array; size specifies the size (in bytes) of each 
member. 


The contents of the array must be in ascending, sorted order. If a match is 
found, the function returns a pointer to the matching member of the array; 
if no match is found, the function returns a null pointer (0). 


Argument compar points to a function that compares key to the array 
elements. The comparison function should be declared as 


int cmp(ptrl1, ptr2) 
void *ptrl, *ptr2; 


The cmp function compares the objects that prt1 and pt r2 point to and re- 
turns one of the following values: 


< 0 if *ptr1 is less than kptr2. 
0 if *ptr1 is equal to kptr2. 
> 0 if *ptri isgreaterthan *ptr2. 
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calloc Allocate and Clear Memory 
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Syntax #include <stdlib.h> 
void *calloc(nmemb, size) 
size_t nmemb; /* number of items to allocate */ 
Size_t size; /* size (in bytes) of each item */ 


Definedin = memory.cinrts.sre 


Description The calloc function allocates size bytes for each of nmemb objects and re- 
turns a pointer to the space. The function initializes the allocated memory 
to all Os. If it cannot allocate the memory (that is, if it runs out of memory), 
it returns a null pointer (0). 


The memory that calloc uses is ina special memory pool or heap. A C mod- 
ule called memory.c reserves memory for the heap in the .bss section. The 
constant MeEMoRY_S1zZE defines the size of the heap as 1000 bytes. If neces- 
sary, you can change the size of the heap by changing the value of 
MEMORY SIZE and recompiling memory.c. For more information, refer to 
Section 4.1.5, Dynamic Memory Allocation, on page 4-5. 


Example This example uses the calloc routine to allocate and clear 10 bytes. 
prt = calloc (10,2) ; /*Allocate and clear 20 bytes */ 
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Ceiling ceil 
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Syntax #include <math.h> 


double ceil (x) 
double x; 


Definedin§ floor.objinrts.lib 


Description The ceil function returns a double-precision number that represents the 
smallest integer greater than or equal to x. 


Example extern double ceil(); 


double answer; 


I 
fs 
oO 


“re 


answer = ceil (3.1415); /* answer 


answer = ceil (-3.5); /* answer = -3.0 */ 
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COS Cosine 
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Syntax 


Defined in 


Description 


Example 
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#include <math.h> 
double cos (x) 
double x; 


sin.objinrts.lib 


The cos function returns the cosine of a floating-point number, x. x is an 
angle expressed in radians. An argument with a large magnitude may 
produce a result with little or no significance. 


double radians, cval; /* cos returns cval * / 
radians = 3.1415927; | 
cval = cos (radians) ; /* return value = -1.0 * / 
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Syntax 


Defined in 


Description 


Example 


Hyperbolic Cosine cosh 
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#include <math.h> 


double cosh (x) 
double x; 


sinh.obj inrts.lib 


The cosh function returns the hyperbolic cosine of a floating-point number, 
x. A range error occurs if the magnitude of the argument is too large. 


double x, y;x = 0.0; 
y = cosh (x); /* return value = 1.0 aa 
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exit Normal Termination 
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Syntax #include <stdlib.h> 


void exit (status) 
int status; 


Definedin exit.cinrts.sre 


Description When a program exits through a call to the exit function, the atexit function 


calls the registered functions (without arguments) in reverse order of their 
registration. 


The exit function does not return. 
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Syntax 


Defined in 


Description 


Example 





exp 


#include <math.h> 


double exp (x) 
double x; 


exp.obj in rts.lib 


The exp function returns the exponential function of real number x. The re- 
turn value is the number e raised to the power x. A range error occurs if the 
magnitude of x is too large. 


double x, y;x = 2.0; 
y = exp (x); /* y = 7.38, which is e**2.0 */ 
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fabs™ Absolute Value, Floating-Point 
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Syntax #include <math.h> 


double fabs (x) 
double x; 


Defined in fabs.obj inrts.lib 
rescipuon: The rene function returns the absolute value of a aloetng: point number, x 


Example "aeanie x, vi 


= eos 
fabs (x) ; /* return value = +57.5 */ 


x 
Yy 
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Syntax 


Defined in 


Description 


Example 


Floor floor 





#tinclude <math.h> 
double floor (x) 
double x; 


floor.objin rts.lib 


The floor function returns a double-precision number that represents the 
largest integer less than or equal to x. 


double answer; 
answer floor (3.1415) ; /* answer = 3.0 af 
answer = floor(-3.5); /* answer = -4.0 ars 
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fmod_ Floating-Point Remainder 
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Syntax #include <math.h> 


double fmod(x, y) 
double x, y; 


Definedin§ = fmod.objin rts.1lib 


Description The fmod function returns the floating-point remainder of x divided by y. If 
y=0, the function returns 0. 


Example double x, y, xr; x = 11.0; 
Vo =D. OF 
r = fmod(x, y); /* fmod returns 1.0 * / 
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Deallocate Memory free 
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Syntax #include <stdlib.h> 


void free(ptr) 
void *ptr; 


Definedin = memory.cinrts.sre 


Description The free function deallocates memory space (pointed to by ptr) that was 
previously allocated by a malloc, calloc, or realloc call. This makes the 
memory space available again. lf you attempt to free unallocated space, the 
function takes no action and returns. For more information, refer to Section 
4.1.5, Dynamic Memory Allocation, on page 4-5. 


Example This example allocates 10 bytes and then frees them. char *x; 
x = malloc(10); /* allocate 10 bytes */ 
free (x); /* free 10 bytes * / 
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7 frexp: “Fraction and Exponent 
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Syntax #include <math.h> 
double frexp(value, exp) a 
double value; /* input Bioeng setae number * / 
int *eXp; /* pointer to exponent Wf 


Defined in frexp. obj inrts.lib 


| Description The frexp function breaks a floating- point number into a normalized fraction 

_..... and an integer power of 2. The function returns a value with a magnitude 

in the range [1/2,1) or 0, so that value = x x 2(** exp). The frexp function 

stores the power in the int pointed to by exp. If value is 0, both parts of the 
result are 0. 


Example double fraction; 
int exp; 
fraction = frexp(3.0, &S&exp) ; 
/* after execution, fraction is .78375 and exp is 2 */ 
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Character Tests . iSXXXXX 
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Syntax 


Defined in 


Description 


#include <ctype.h> 


int 


isalnum(c) 


char c; 
int isalpha(c) 
char c; 
int isascii (c) 
char c; 
int iscntrl (c) 
char c; 
int isdigit (c) 
char c; 
int isgraph (c) 
char c; | 

int islower(c) _ 

+ sehar Ce. 

int isprint (c) 
char c; 

int ispunct (c) 
char -c; 

int isspace (c) 
char c; 

int isupper (c) 
char c; 

int isxdigit (c) 
char cc}; 


isxxx.c and ctype.cinrts.sre 
Also defined in ctype.h aS macros 


These functions test a single argument c to see if it is a particular type of 
character—alphabetic, alohanumeric, numeric, ASCIl, etc. If the test is true 
(the character is the type of character that it was tested to be), the function 
returns a nonzero value; if the test is false, the function returns 0. The char- 
acter typing functions include 


isainum 
isalpha 


isascii 
iscntrl 
isdigit 
isgraph 


identifies alphanumeric ASCII characters (tests for any char- 
acter for which isalpha or isdigit is true). 


identifies alphabetic ASCII characters (tests for any character 
for which islower or isupper is true). 


identifies ASCII characters (any character between 0—127). 


identifies control characters (ASCII character 0—31 and 
127). 


identifies numeric characters (‘0’— ‘9’) 
identifies any nonspace character. 
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iSXXXXX Character Tests 
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islower identifies lowercase alphabetic ASCII characters. 

isprint identifies printable ASCII characters, including spaces (ASCII 
characters 32—126). 

ispunct identifies ASCII punctuation characters. 

isspace identifies ASCII spacebar, tab (horizontal or vertical), carriage 


return, formfeed, and newline characters. 
isupper identifies uppercase ASCII alphabetic characters. 
isxdigit identifies hexadecimal digits (O—9, a—f, A—F). 


The C compiler also supports a set of macros that perform these same func- 
tions. The macros have the same names as the functions but are prefixed 
with an underscore; for example, _isascii is the macro equivalent of the 
isascii function. In general, the macros execute more efficiently than the 
functions. 


5-38 Runtime-Support Functions 


Multiply by a Power of Two \dexp 


Syntax #include <math.h> 


double ldexp(x, exp) 
double x; 
int exp; 


Definedin§ idexp.objin rts.lib 


Description The \idexp function multiplies a floating-point number by a power of 2 and 
returns x x 2°*P, exp can be a negative or a positive value. A range error 
may occur if the result is too large. 


Example double result; 
result ldexp(1.5, 5); /* result is 48.0 * / 
result = ldexp(6.0, -3); /* result is 0.75 * / 
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log ‘Natural Logarithm 
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Syntax #include <math.h> 


double log (x) 
double x; 


Defined in log.objinrts.1lib 


Description The log function returns the natural logarithm ofa real number, x. Adomain 
error occurs if x is negative; a range error occurs if x Is 0. 
Example float x, y; 
x = 2.718282; 
y = log(x);_ /* Return value = 1.0 * / 
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Common Logarithm log10 
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Syntax 


Defined in 


Description 


Example 


#include <math.h> 


double 1logl10 (x) 
double x; 


log.obj in rts.1lib 


The log10 function returns the base-10 logarithm of a real number, x. A 
domain error occurs if x is negative; a range error occurs if x is 0. 


£loat %,. ye 


x = 10.0; 
y = log(x); /* Return value = 1.0 * / 
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Itoa Long Integer to ASCII 
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Syntax #include <stdlib.h> 


int ltoa(n, buffer) 
long n; /* number to convert af 
char *buffer; /* buffer to put result in * / 


Definedin§ jitoa.cinrts.sre 


Description The ltoa function converts a long integer to the equivalent ASCII siring. If 
the input number n is negative, a leading minus sign is output. The ltoa 
function returns the number of characters placed in the buffer. 
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Syntax 


Defined in 


Description 


Allocate Memory malloc 
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#include <stdlib.h> 
void *malloc (size) 
size t size; /* Size Of block: 10 ‘bytes. */ 


memory.cinrts.src 


The malloc function allocates space for an object of size bytes and returns 
a pointer to the space. If malloc cannot allocate the packet (that is, if it runs 
out of memory), it returns a null pointer (0). This function does not modify 
the memory it allocates. 


The memory that malloc uses is in a special memory pool or heap. A C mod- 
ule called memory .c reserves memory for the heap in the .bss section. The 
constant MEMory_s1zE defines the size of the heap as 1000 bytes. If neces- 
sary, you can change the size of the heap by changing the value of 
MEMORY SIZE and recompiling memory.c. For more information, refer to 
Section 4.1.5, Dynamic Memory Allocation, on page 4-5. 
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memchr Find First Occurrence of Character 
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Syntax 


Defined in 


Description 
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#include <string.h> 
void *memchr(s, c, n) 

void *S; 

char ce 

size t n; 
memchr.cinrts.sre 


The memchr function finds the first occurrence of c in the first n characters 
of the object that s points to. If the character is found, memchr returns a 
pointer to the located character; otherwise, it returns a null pointer (0). 


The memchr function is similar to strchr, except the object that memchr 
searches can contain values of 0, and c can be 0. 
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Memory Compare mMmemcmp 
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Syntax #include <string.h> 


int memcmp(sl, s2, n) 
void *sl, *s2; 
size t n; 


Definedin = memcmp.cinrts.srce 


Description The memcmp function compares the first n characters of the object that s2 
points to with the object that s1 points to. The function returns one of the 
following values: 


< 0 if *s1 is less than *s2,. 
0 if *s1 is equal to *s2,. 
> 0 if *s1 is greaterthan *s2. 


The memcmp function is similar to strncmp, except that the objects 
memcmp compares can contain zeros. 
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memcpy Memory Copy 
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Syntax 


Defined in 


Description 
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#include <string.h> 
void *memcpy(sl1, s2, n) 
void *sl, *s2; 

size t n; 
memmov.cinrts.srec 


The memcpy function copies n characters from the object that s2 points to 
into the object that s1 points to. /f you attempt to copy characters of overlap- 
ping objects, the function’s behavior is undefined. The function returns the 
value of s1. 


The memcpy function is similar to strncpy, except that the objects memcpy 
copies can contain zeros. 
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Syntax #include <string.h> 
void *memmove(sl, s2, n) 
void ksl, *s2; 
S226 0 on; 
Defined in memmov.cinrts.src 


Description The memmove function moves n characters from the object that s2 points 
to into the object that s1 points to; the function returns the value of si. The 
memmove function correctly copies characters between overlapping 
objects. 
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memset Copy Character into Memory 
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Syntax #include <string.h> 


void *memset(s, c, n) 
void *s; 
char oc; 
size t n; 


Definedin memset.cinrts.srce 


Description The memset function copies the value of c into the first n characters of the 
object that s points to. The function returns the value of s. 
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Reset All Dynamic Memory minit 
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Syntax #include <stdlib.h> 
void minit() 
Definedin = memory.cinrts.sre 


Description The minit function resets all the space that was previously allocated by calls 
to the malloc, calloc, or realloc functions. 





n Al mnadisla 
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Fan’ + 
The memory that Minit uses is ina special memcry poo! 


called memory.c reserves memory for the heap in the .bss section. The con- 
stant MEMoRY_s1zE defines the size of the heap as 1000 bytes. If necessary, 
you can change the size of the heap by changing the value of MEMoRY SIZE 
and reassembling memory.c. For more information, refer to Section 4.1.5, 
Dynamic Memory Allocation, on page 4-5. 


= 
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modf _Signed Integer and Fraction 
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Syntax 


Defined in 


Description 


Example 
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#include <math.h> 


double modf(value, iptr) 
double value; 
int cay ol a 


modf.objinrts.lib 


The modf function breaks a value into a signed integer and a signed frac- 
tion. Each of the two parts has the same sign as the input argument. The 
function returns the fractional part of value and stores the integer as a 
double at the object pointed to by iptr. 


double value, ipart, fpart; 
value = -3.1415; 


fpart = modf(value, &ipart); 


/* After execution, ipart contains -3.0, * / 
/* and fpart contains -0.1415. * / 
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Syntax 


Defined in 


Description 


Move Memory mMovmem 


#include <stdlib.h> 


char *movmem(src, dest, count) 
char *sre + /* source address * / 
char *dest; /* destination address x / 
char count; /* number of bytes to move * / 


movmem.cin rts.src 


The movmem function moves count bytes of memory from the object that 
src points to into the object that dest points to. The source and destination 
areas can be overlapping. 
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pow Aaise to a Power 


Syntax 


Defined in 


Description 


Example 
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#include <math.h> 


double pow(x, y) 
double x, y; /* Raise x to power y */ 


pow.obj in rts.lib 


The pow function returns x raised to the power y. A domain error occurs if 


x = Qandy <0, orif x is negative and y is not an integer. A range error 
may occur. 


double x, y, Z; 


x = 2.0; 
y = 3.0; 
x = pow(x, y); /* return value = 8.0 “id 
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Array Sort qsort 
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a t 
Syntax #include <stdlib.h> 


Fields 


Description 


void qsort (base, nmemb, size, compar) 
void xbase; 
size t nmemb, size; 
int (*compar) (); 


gsort.cinrts.src 


The qsort function sorts an array of nmemb members. Argument base points 
to the first member of the unsorted array; argument size specifies the size 
of each member. 


This function sorts the array in ascending order. 


Argument compar points to a function that compares key to the array 
elements. The comparison function should be declared as 


ime, -cmp(ptri;. ptr2) 
void *ptrl, *ptr2; 
The cmp function compares the obiects that pt r1 and pt r2 point to and re- 
turns one of the following values: 
< 0 if *ptri is less than kptr2. 


0 if *ptr1 is equal to *ptr2. 
> 0 if *ptri1 is greaterthan *ptr2. 
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rand/srand Pseudo-Random Integers 
ROR RUE RERER ERR E RRR RRR RE RRRR RRR RRA ARERR RRR RSE RR RRR RRR RRR RRR RRR RRR RRR RRR RR RR ROR RRR RRR RRR REX RUS I SU RU 
Syntax #include <stdlib.h> 

int rand( ) 


void srand (seed) 
unsigned int seed; 


Fields rand.cinrts.sre 


Description Two functions work together to provide pseudo-random sequence 
generation: 


C4 The rand function returns pseudo-random integers in the range 
0-RAND_MAX. 


(4 The srand function sets the value of seed so that a subsequent call to 
the rand function produces a new sequence of pseudo-random num- 
bers. The srand function does not return a value. 


If you call rand before calling srand, rand generates the same sequence it 
would produce if you first called srand with a seed value of 1. If you call srand 
with the same seed value, rand generates the same sequence of numbers. 
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Fields 


Description 
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Change Size of Allocated Memory realloc 


#include <stdlib.h> 


void *realloc(ptr, size) 
void *ptr; /* pointer to object to change ae 4 
size t size; /* ew Size: (in. bytes) -of. packet */ 


memory.cinrts.sre 


The realloc function changes the size of the allocated memory pointed to 
by ptr, to the size specified in bytes by size. The contents of the memory 
space (up to the lesser of the old and new sizes) is not changed. 


Ci If ptr is 0, then realloc behaves like malloc. 


If ptr points to unallocated space, the function takes no action and 
returns. 


Cl 
Ca lf the space cannot be allocated, the original memory space is not 
changed and realloc returns 0. 

Cd 


If size=0 and ptr is not null, then realloc frees the space that ptr 
points to. 


If the entire object must be moved to allocate more space, realloc returns 
a pointer to the new space. Any memory freed by this operation is deallo- 
cated. If an error occurs, the function returns a null pointer (0). 


The memory that realloc uses is ina special memory pool or heap. A C mod- 
ule called memory.c reserves memory for the heap in the .oss section. The 
constant MEMORY _S1ZE defines the size of the heap as 1000 bytes. If neces- 
sary, you can change the size of the heap by changing the value of 
MEMORY SIZE and recompiling memory.c. For more information, refer to 
Section 4.1.5, Dynamic Memory Allocation, on page 4-5. 
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Syntax 


Fields 


Description 


Example 
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#include <math.h> 


double sin (x) 
double x; 


sin.obj in rts.lib 


The sin function returns the sine of a floating-point number, x. Argument x 
is an angle expressed in radians. An argument with a large magnitude may 
produce a result with little or no significance. 


double radian, sval; /* sval is returned by sin */ 


radian = 3.1415927; 
sval = sin(radian) ; /* -1 is returned by sin x / 
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Syntax 


Fields 


Description 


Example 


Hyperbolic Sine sinh 
#include <math.h> 


double sinh (x) 
double x; 


sinh.objinrts.lib 


The sinh function returns the hyperbolic sine of a floating-point number, x. 
A range error occurs if the magnitude of the argument is too large. 


double x, y; 
x = 0.0; 
y = sinh(x); /* return value = 0.0 */ 
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Synt incl 
yntax include <math.h> 


double sqrt (x) 
double x; 


Fields sqrt.objinrts.lib 


Description The sart function returns the nonnegative square root of a real number x. 
A domain error occurs if the argument is negative. 


Example double x, y; 
x = 100.0; 
y = sqrt (x); /* return value = 10.0 a) 
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Concatenate Strings strcat 
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Syntax #include <string.h> 


char *strceat(sl, s2) 
char *sl, *s2; 


Fields strcat.cinrts.sre 


Description The strcat function appends a copy of s2 (including a terminating null char- 
acter) to the end of s1. The initial character of s2 overwrites the null charac- 
ter that originally terminated s1. The function returns the value of si. 


5-59 


strchr Find 


irst Occurrence of Character 
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Syntax #include <string.h> 
char *strchr(s, c) 
char *s; 
| char c; 
Fields strchr.cinrts.sre 


Description The strchr function finds the first occurrence of c (which is first converted 
to a char) in s. If strchr finds the character, it returns a pointer to the 


character; otherwise, it returns a null pointer (0). 
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String Compare strcmp/strcoll 
Syntax #include <string.h> 
int strcoll(sl1, s2) 
char *sl, *s2; 
int strcmp(sl, s2) 
char *sl, *s2; 
Fields stremp.cinrts.srce 
Description The strcmp and strcoll functions compare s2 with si. The functions are 


equivalent; both functions are supported to provide compatibility with ANSI 
C. 


The functions return one of the following values: 


< 0 if *s1 is less than *S2. 
0 if *s1 is equal to *s2,. 
> 0 if *si is greaterthan *s2. 
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strcpy String C 
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Synt lud h> 

yntax include <string. 


char *strcepy(sl1, s2) 
char *sl, *s2; 


Fields strepy.cinrts.sre 


Description The strcpy function copies s2 (including a terminating null character) into 
sl. If you attempt to copy strings that overlap, the function’s behavior is 
undefined. The function returns a pointer to the destination string. 
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Find Number of Unmatching Characters strcspn 
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Syntax #include <string.h> 


size_t strespn(sl, s2) 
char *S1,).-SS25 


Fields strespn.cinrts.sre 


Description The strcspn function returns the length of the initial segment of s1 which is 
entirely made up of characters that are not in s2. \f the first character in s1 
is in s2, the function returns 0. 
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strerror Siring Errors 
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Syntax #include <string.h> 


char *strerror (errnum) 
int errnum; 


Fields strerror.cinrts.sre 


Description The strerror function returns the string “function error”. This function 
is supplied to provide ANSI compatibility. 
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String Length _ strien 
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Syntax #include <string.h> 


size t strlen(s) 
char  *s; 


Fields strlen.cinrts.src 


Description The strlen function returns the length of s. In C, a character string is termi- 
nated by the first byte with a value of 0 (anull character). The returned result 
does not include the terminating null character. 


5-65 


strncat Concatenate Strings 
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Syntax #include <string.h> 


char *strncat(sl, s2, n) 
char *sl, *s2; 
size t n; 


Fields strncat.cinrts.sre 


Description The strncat function appends up to n characters of s2 (including a terminat- 
ing null character) to the end of s1. The initial character of s2 overwrites the 
null character that originally terminated s1; strncat appends a null character 
to result. The function returns the value of s1. 
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Syntax #include <string.h> 


int strncmp(sl, s2, n) 
char *sl, *s2; 
size t n; 


Fields strnomp.c in rts.sre 


Compare Strings strncmp 


Description The strncmp function compares up to n characters of s2 with si. The 


function returns one of the following values: 


< 0 if *s1 is less than *s2, 
0 if *s1 is equal to *s2, 
> 0 if *si isgreaterthan *s2. 
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strncpy String Copy 
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Syntax #include <string.h> 


char *strncpy(sl, s2, n) 
char *sl, *s2; 
Size t n; 


Fields strnepy.cinrts.sre 


Description The strncpy function copies up to n characters from s2 into s1. If s2 isn char- 
acters long or longer, the null character that terminates s2 is not copied. If 
you attempt to copy characters from overlapping strings, the function’s be- 
havior is undefined. If s2 is shorter than n characters, strncpy appends null 
characters to s1 so that s1 contains n characters. The function returns the 


value of s1. 
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Syntax 


Fields 


Description 


Find Any Matching Character strpbrk 
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#include <string.h> 


char *strpbrk(sl1, s2) 
char *sl, *s2; 


strpbrk.cin rts.sre 


The strpbrk function locates the first occurrence in s1 of anycharacter in s2. 


If strpbrk finds a matching character, it returns a pointer to that character; 
otherwise, it returns a null pointer (0). 
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strrchr Find Last Occurrence of Character 
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Synt. #3 
yntax include <string.h> 


char *strrchr(s ,c) 
char *s; 
ante oc? 


Fields strrchr.cinrts.sre 


Description The strrchr function finds the last occurrence of c in s. If strrchr finds the 
character, it returns a pointer to the character; otherwise, it returns a null 


pointer (0). 
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Find Number of Matching Characters _Strspn 
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Syntax #include <string.h> 


size t *strspn(sl, s2) 
int *s1l, *s2; 


Fields strspn.cinrts.sre 


Description The strspn function returns the length of the initial segment of s1 which is 
entirely made up of characters in s2. lf the first character of s1 is notin s2, 
the strspn function returns 0. 
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str 


Syntax 


Fields 


Description 
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#include <string.h> 


char *strstr(sl1, s2) 
char *sl, *s2; 


strstr.cinrts.sre 


The strstr function finds the first occurrence of s2 in s1 (excluding the termi- 
nating null character). If strstr finds the matching string, it returns a pointer 
to the located string; if it doesn’t find the string, it returns a null pointer. If s2 
points to a string with length 0, then strstr returns s1. 
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Fields 


Description 
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#include <stdlib.h> 
double strtod(nptr, endptr) 


char *nptr; 
char “**endptr; 


long int strtol(nptr, endptr, base) 


char “*nptr? 
char **endptr; 
int base; 


unsigned long int strtoul(nptr, endptr, base) 


char “*nptr;? 
char **endptr; 
int base; 


strtod.cinrts.srce 


strtol.cinxrts.srce 


strtoul.cinrts.srce 


Three functions convert ASCII strings to numeric values. For each function, 
argument nptr points to the original string. Argument endptr points to a 
pointer; the functions set this pointer to point to the first character after the 
converted string. The functions that convert to integers also have a third ar- 
gument, base. 


Ch 


Ca 


The strtod function converts a string to a floating-point value. The string 
must have the following format: 

[space] [sign] digits [.digits] [e/E [sign] integer] 

The function returns the converted string; if the original string is empty or 
does not have the correct format, the function returns a 0. If the con- 
verted string would cause an overflow, the function returns 
+HUGE_VAL; if the converted string would cause an underflow, the 
function returns 0. If the converted string causes an overflow or an un- 
derflow, errno is set to the value of ERANGE. 

The strtol function converts a string to a long integer. The string must 
have the following format: 

[space] [sign] digits [.digits] [e/E [sign] integer] 

The strtoul function converts a string to an unsigned long integer. The 
string must be specified in the following format: 

[space] [sign] digits [.digits] [e/E [sign] integer] 


The space is indicated by a spacebar, horizontal or vertical tab, carriage re- 
turn, form feed, or newline. Following the space is an optional sign, and then 
digits that represent the integer portion of the number. The fractional part 
of the number follows, then the exponent, including an optional sign. 


The first unrecognized character terminates the string. The pointer that 
endptr points to is set to point to this character. 
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strtok Break String into Tok 
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yntax include <string.h> 


char *strtok(sl1, s2) 
char *sl, *s2; 


Fields strtok.cinrts.sre 


Description Successive calls to the strtok function break si into aseries of tokens, each 


delimited by a character from s2. Each call returns a pointer to the next 
token. 
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Tangent tan 
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Syntax 


Fields 


Description 


Example 


#include <math.h> 


double tan (x) 
double x; 


tan.obj inrts.lib 


The tan function returns the tangent of a floating-point number, x. Argument 
xis an angle expressed in radians. An argument with a large magnitude may 
produce a result with little or no significance. 


double x, y; 


3314159277420; 
tan (x) ; /* return value = 1.0 * / 


x 
Y 
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tanh Hyperbolic Tangent 
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Syntax #include <math.h> 


double tanh (x) 
double x; 


Fields tanh.obj in rts.1lib 


Description The tanh function returns the hyperbolic tangent of a floating-point number, 
xe 


Example double x, y; 
x = 0.0; : 
y = tanh(x); /* return value = 0.0 ay 
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Convert to ASCII toascli 
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Syntax #include <ctype.h> 
int toascii (c) 
char oc; 
Fields toascii.cin rts.sre 


Description The toascii function ensures that c is a valid ASCII character by masking the 
lower seven bits. There is also a toascii macro. 
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tolower/toupper Convert Case 
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Syntax #include <ctype.h> 


int tolower(c) 
char cs 


int toupper(c) 
char c; 


Fields tolower.cinrts.scr 
toupper.cinrts.sre 


Description Two functions convert the case of a single alphabetic character, c, to upper 
or lower case: 


Ca The tolower function converts an uppercase argument to lowercase. 
If c is already in lowercase, tolower returns it unchanged. 


La The toupper function converts a lowercase argument to uppercase. If 
c is already in uppercase, toupper returns it unchanged. 


The functions have macro equivalents named _tolower and _ toupper. 
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Syntax 


Description 


Example 


_Variable-Argument | Macros va. _arg/va_ end/va_ Start 
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#include <stdarg.h> 


type va_arg(ap, type) 
void va_end(ap) 
void va_start(ap, parmN) 

va_list *ap 
Some functions can be called with a varying number of arguments that have 
varying types. Such a function, called a variable-argument function, can use 
the following macros to step through its argumentlist at run time. The ap pa- 
rameter points to an argument in the variable-argument list. 


La The va_start macro initializes ap to point to the first argument in an ar- 
gument list for the variable-argument function. The parmN parameter 

_ points to the rightmost parameter in the fixed, declared list. 

La The va_arg macro returns the value of the next argument in a call toa 
variable-argument function. Each time you call va_arg, it modifies ap so 
that successive arguments for the variable-argument function can be 
returned by successive calls to va_arg (va_arg modifies ap to point to 
the next argument in the list). The type parameter is a type name; it is 
the type of the current argument in the list. 


Lk The va_end macro resets the stack environment after va_start and 
va_arg are used. 


Note that you must call va_start to initialize ap before calling va_arg or 
va_end. 


int- “printer (fmt) /* Has 1 fixed argument and xy 
char *fmt /* additional variable arguments x / 
{ 
int. 23 
char *s; 
Long 17 


va_list ap; 


va_start(ap,fmt); /* initialize x / 

/* Get next argument, an integer sa 
i = va_arg(ap, int); 

/* Get next argument, a string * / 
S = va_arg(ap, char *); 

/* Get next argument, a long * / 
1 = va_arg(ap, long); 
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va_end (ap) /* Reset */ 


5-80 Runtime-Support Functions 


Appendix A 


Fatal Errors 





Compiler error messages are displayed in the following format, which 
shows the line number in which the error occurs and the text of the message: 


name.c, line n: error message 


All the errors listed in this section cause the compiler to abort immediately. 
Text in italics in these error messages Is replaced with actual text from the 
program, your own symbols, filenames, memory allocations, etc. 


Cannot allocate sufficient memory:The compiler requires a minimum of 
512K bytes of memory to run; this message indicates that this amount is not 
available. Supply more dynamic RAM. 


Can’t open filename as source:The compiler cannot find the file name as 
entered. Check for spelling errors and check to see that the named file ac- 
tually exists. 


Can’t open filename as intermediate file: The compiler cannot create the 
output file. This is usually caused by either an error in the syntax of the file- 
name or by a full disk. 


lilegal extension ext on output file: The intermediate file cannot have a 
.c extension. 


Fatal errors found: no intermediate file produced: This message Is 
printed after an unsuccessful compilation. Correct the errors (other mes- 
sages indicate particular errors) and try compilation again. 


Too many errors: aborting: An error has occurred that prevents the com- 
piler from continuing. 


Cannot recover from earlier errors: aborting: An error has occurred that 
prevents the compiler from continuing. 
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Appendix B 


C Preprocessor Directives 





The C preprocessor provided with this package is standard and follows Ker- 
nighan and Ritchie exactly. This appendix summarizes the directives that 
the preprocessor supports. Generally, the directives are organized alpha- 
betically, one directive per page; however, related directives (such as 
#it/Helse) are presented together on one page. Here is an alphabetical table 
of contents for the preprocessor directives reference: 


Directive Page 
PA OTIIG: woireiets sebaih dict eae ech awe ean nae eee ene eee 8a B-2 
POTS ip od et SE ca cht Wie See eh aeRO Rane ain eee a ees B-3 
POTICIT 3 ko oe cxtncitcn netted auaente eed a ae ie Ra Pace Snare ata B-3 
PE ao oe fg tag Rise cap tice Wud ea Au gideens ade ra a ane lee Mey anew en B-3 
PED cea Se inte ccitn sae cle ak eA Us RA EA RO Rees B-3 
BEATIN. suck. cdc axe ess Bee Seat ED ee last cay AP anette ae oh DANN B-3 
SPU H ICG. secicicose eraebxts os bce ace ah ue sea eI Oe dh Sone ae B-—5 
PG ieckect nae dex as hare da ee OR od naw ata tes B-6 
SAICIEL | .w.o:0.eie dca oe Bie Cli ES hd ROR Eee ee B-2 
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#define/#u ndet Detine/Undefine Constant Directives 
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Syntax 


Description 


Example 
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#define name [ (arg,...,arg) ] token-string 


#undef name 


The preprocessor supports two directives for defining and undefining con- 
stants: 


Ch 


a 


The #define directive assigns a string to a constant. Subsequent occur- 
rences of name (whichcan be immediately followed by an argument list) 
are replaced by token-string. The namecan be immediately followed by 
an argument list; the arguments are separated by commas, and the list 
is enclosed in parentheses. Each occurrence of an argument.is re- 
placed by the corresponding set of tokens from the comma-separated 
string. 


When a macro with arguments is expanded, the arguments are placed 
into the expanded token-string unchanged. After the entire token-string 
is expanded, the preprocessor scans again for names to expand at the 
beginning of the newly created token-string, which allows for nested 
macros. 


Note that there is no space between name and the open parenthesis at 
the beginning of the argument list. A trailing semicolon is not required; if 
used, it is treated as part of the token-string. 


The #undef directive undefines the constant name; that is, itcauses the 
preprocessor to forget the definition of name. 


The following example defines the constant f: 


#define f(a,b,c) 3*atb-c 
The following line of code uses the definition of £: 


f (27,begin, minus) 


This line is expanded to: 


3*27+begin-minus 


To undefine £, enter: 


#undef f 


C Preprocessor Directives 


Syntax 


Description 


- Conditional Processing Directives #it/#ifdet/#ifndef/#else/#endif 
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#if constant-expression 
code to compile if condition is true 


[#else 
code to compile if condition is false] 


#endif 


#ifdef name 
code to compile if name is defined 


[#else 
code to compile if name is not defined | 


#endif 


#ifndef name 
code to compile if name is not defined 


[#else 
code to compile if name is defined| 


#endif 
The C preprocessor supports several conditional processing directives: 
14 Three directives can begin a conditional block: 


@ The #if directive tests an expression. The code following an #if di- 
rective (up to an #else or an #endif) is compiled if the constant-ex- 
pressionevaluates to a nonzero value. All binary non-assignment C 
operators, the ?: operator, the unary -, !, and ! operators are legal in 
constant-expression. The precedence of the operators is the same 
as in the definition of the C language. The preprocessor also sup- 
ports a unary operator named defined, which can be used in con- 
stant-expression in one of two forms: 


1) defined (<name>) or 
2) defined <name> 


This allows the utility of #ifdef and #ifndef in an #if directive. Only 
these operators, integer constants, and names which are known by 
the preprocessor should be used in constant-expression. |n partic- 
ular, the sizeof operator should not be used. 


m The #ifdef directive tests to see if name is a defined macro. The 
code following an #ifdef directive (up to an #else or an #endif) is 
compiled if name is defined (by the #define directive) and it has not 
been undefined by the #undef directive. 


m@ The #ifndef directive tests to see if name is not a defined macro. 
The code following an #ifndef directive (up to an #else or an #endif) 
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#it/#itdet/#indet/#else/#endit Conditional Processing Directives 
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is compiled if name is not been defined (by the #define directive) or 
if it has been undefined by the #undef directive. 
Ca oe #else directive begins an alternate block of code that is compiled 
if: 
m The condition tested by #if is false. 
The name tested by #ifdef is not defined. 
mH 8 =6The name tested by #ifndef is defined. 


Note that the #else portion of a conditional block is optional, if the #if, 
#ifdef, or #ifndef test is not successful, then the preprocessor continues 
with the code following the #endif. 


La The #endif directive ends aconditional block. Each #if, #ifdef, and #ifn- 
def directive must have a matching #endif. Conditional compilation se- 
quences can be nested. 


C Preprocessor Directives 
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Description 
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#include ” filename ” 


or 


#include < filename > 


The #include directive tells the preprocessor to read source statements 
from another file. The preprocessor includes (at the point in the code where 
#include is encountered) the contents of the filename, which are then pro- 
cessed. Youcan enclose the filename in double quotes or in angle brackets. 


The filename can be acomplete pathname or a filename with no path infor- 


mation. 


(Ld 


Ch 


lf you provide path information for filename, the preprocessor uses that 
path and does not look for the file in any other directories. 


If you do not provide path information and you enclose the filename in 
double quotes, the preprocessor searches for the file in 


1) 


2) 
3) 


The directory that contains the current source file. (The current 


source iiie réfers to ine file inat is being processed wnen 


cessor encounters the #include directive.) 
Any directories named with the —i preprocessor option. 


Any directories named with the C_DIR environment variable. 


If you do not provide path information and you enclose the filename in 
angle brackets, the preprocessor searches for the file in 


1) 
2) 


Any directories named with the —i preprocessor option. 


Any directories named with the C_DIR environment variable. 


CC ee ey 


Note: 


If you enclose the filename in angle brackets, the preprocessor does not 
search for the file in the current directory. 
i tricep apr cesses 


For more information about the —i option and the environment variable, read 
Section 2.2.1.1 on page 2-8. 
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#line Line Control Directive 
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Syntax #line integer-constant [ filename” | 

Description The #line directive generates line control information for the next pass of the 
compiler. The integer-constant is the line number of the next line, and the 
filename is the file where that line exists. If you do not provide a filename, 
the current filename (specified by the last #line directive) is unchanged. 


This directive effectively sets the LINE and__ FILE _ symbols. 


C Preprocessor Directives 


Index 





~—al shell program option, 2-3 

alternate directories, 2-8 

—ap snéli program opiion, 2-3 

ARO (SP), 4-4, 4-6, 4-8 

AR1 (FP), 4-4, 4-6, 4-8 

AR2, 4-6 

archiver, 1-3, 2-20 

—as shell program option, 2-4 

asm statement, 3-9, 4-14 

assembler, 1-3, 2-2, 2-3 

assert macro, 5-2 

assert.h header, 5-2, 5-8 

autoinitialization, 2-17, 4-3, 4-21, 4-22 
RAM model, 2-18, 4-21, 4-22 
ROM model, 2-17, 4-21, 4-22 

—ax shell program option, 2-4 


bit addressing, 4-5 
boot.obj, 2-15, 2-17, 2-19, 4-4 
.bss section, 4-2, 4-3, 4-4 





—c linker option, 2-15, 4-3 
—c preprocessor option, 2-6 
—c shell program option, 2-3 


C_DIR environment variable, 2-9 
c_intO, 2-16 
calloc function, 4-5 
character typing conversion functions 
isalnum, 5-37 
isalpha, 5-37 
isascil, 5-37 
iscntrl, 5-37 
isdigit, 5-37 
isgraph, 5-37 
islower, 5-37 
isprint, 5-37 
ispunct, 5-37 
isspace, 5-37 
isupper, 5-37 
isxdigit, 5-37 
toascii, 5-77 
tolower, 5-78 
toupper, 5-78 
character typing/conversion functions, 5-3, 
5-8 
.cinit, 2-17 
.cinit section, 4-2, 4-20, 4-21 
code generator, 2-5 
dspcg, 2-13 
invocation, 2-13 
options 
—0, 2-13 
—q, 2-14 
—Z, 2-14 
compiler operation, 2-1—2-20 
—cr linker option, 2-15, 4-4 
ctype.h header, 5-3, 5-8 
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~—d preprocessor option, 2-6 
data section, 4-3 
data types, 3-5 
data sizes, 3-5 
dedicated registers, 4-6 
#define directive, B-2 
derived types, 3-4 
diagnostic messages, 5-2 
assert, 5-20 
NDEBUG macro. See NDEBUG macro 


div_t type, 5-7 

division and modulus, 4-18 
—dNAME shell program option, 2-3 
dspcc, 2-11 

dspcg, 2-13 

dspcl, 2-3 

dspcpp, 2-6 

dynamic memory allocation, 4-5 





#else directive, B-3 
emulator, 1-3 
#endif directive, B-3 
entry points 
C code, 2-16—2-20 
_c_int0, 2-16 
reset vector, 2-16 
enum, 3-7 
enumeration declaration, 3-7 
environment variable, 2-9 
EPROM programmer, 1-3 
error message macros, 5-8 
assert, 5-20 
error messages, A-1 
expression analysis 
floating point, 4-19 
integers, 4-18 
external definitions, 3-7 
external variables, 4-3 
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fatal errors, A-1 
field manipulation, 4-5 
float.h header, 5-3 
floating-point expression analysis, 4-19 
floating-point math functions, 5-9 
acos, 5-18 
asin, 5-19 
atan, 5-21 
atan2, 5-22 
ceil, 5-27 
cos, 5-28 
cosh, 5-29 
exp, 5-31 
fabs, 5-32 
floor, 5-33 
fmod, 5-34 
frexp, 5-36 
ldexp, 5-39 
log, 5-40 
logi0, 5-41 
modf, 5-50 
pow, 9-52 
sin, 5-56 
sinh, 5-57 
sqrt, 5-58 
tan, 5-75 
tanh, 5-76 
FP register, 4-4, 4-6, 4-8 
frame pointer, 4-6, 4-8 
function call conventions, 4-8—4-22 
local frame generation, 4-8 
passing parameters, 4-8 
terminating a function, 4-9 
termination, 4-9 
function calls, using the stack, 4-4 





—g shell program option, 2-3 
general utility functions, 5-7, 5-11 
abort, 5-16 
abs, 5-17 
atexit, 5-23 
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bsearch, 5-25 
calloc, 5-26 
exit, 5-30 
free, 5-35 
labs, 5-17 
malloc, 5-43 
minit, 5-49 
movmem, 5-51 
qsort, 5-53 
rand, 5-54 
realloc, 5-55 
srand, 5-54 
strtod, 5-73 
strtol, 5-73 
strtoul, 5-73 


global variables, 3-9, 4-3 
reserved space, 4-2 


hardware requirements (PC systems), 1-4 

header files, 5-2—5-7 
assert.h header, 5-2 
ctype.h header, 5-3 
float.h header, 5-3 
limits.h header, 5-3 
math.h header, 5-5 
stdarg.h header, 5-6 
stddef.h header, 5-6 
stdlib.h header, 5-7 
string.h header, 5-7 


heap, 4-5 








—i preprocessor option, 2-7, 2-8 
—i shell program option, 2-3 
identifiers, 3-2 

#if directive, B-3 

#ifdef directive, B-3 

#ifndef directive, B-3 

#include, 2-8 

#include directive, B-5 
includes, 2-8 
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initialized sections, 4-2 
inline assembly construct (asm), 3-9, 4-14 
installation, 1-4 
Macintosh, 1-4 
MPW, 1-4, 1-7 
OS/2, 1-4 
PC, 1-4 
PC-DOS, 1-4 
Sun-3 workstation, 1-4 
Sun-OS, 1-4, 1-6 
Ultrix, 1-4, 1-6 
VAX, 1-4 
VMS, 1-4, 1-5 
integer expression analysis, 4-18 
division and modulus, 4-18 
overflow and underflow, 4-18 
interfacing C and assembly language, 
4-11—4-15 
asm statement, 4-14 
assembly language modules, 4-11 
defining variables in assembly language, 
4-13 
inline assembly language, 4-14 
modifying compiler output, 4-15 
interrupt handling, 4-16 
invoking the 
assembler, 1-4 
batch files, 1-4 
code generator, 2-5 
linker, 2-15 
parser, 2-5 
preprocessor, 2-5 
invoking the assembler, 2-2 





—k shell program option, 2-3 
Kernighan and Ritchie 

preprocessor, 2-7 

The C Programming Language, 1-1 
keywords, 3-2 






—l linker option, 2-15 
Idiv_t type, 5-7 
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Index 


limits 
floating-point types, 5-3, 5-5 
integer types, 5-3 
limits.h header, 5-3 
#line directive, B-6 
linker, 1-3, 2-15—2-20 
linker command file, 2-16 
linking C code, 2-15—2-20 
local frame generation, 4-8 
local variable pointer, 4-6 


—ma shell program option, 2-3 
Macintosh installation, 1-7 
malloc function, 4-5 


math.h header, 5-5, 5-9 
directives 
#define, B-2 
#else, B-3 
#endif, B-3 
#if, B-3 
#ifdef, B-3 
#ifndef, B-3 
#include, B-5 
#line, B-6 
#undef, B-2 
floating-point math functions, 5-5 


memory management functions 
calloc, 5-26 
free, 5-35 
malloc, 5-43 
minit, 5-49 
movmem, 5-51 
realloc, 5-55 
memory model, 4-2—4-22 
allocating variables, 4-3 
dynamic memory allocation, 4-5 
field manipulation, 4-5 
RAM model, 4-3 
ROM model, 4-3 
runtime stack, 4-4 
sections, 4-2 
structure packing, 4-5 
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memory.c, 4-5 
MEMORY_SIZE constant, 4-5 
modulus, 4-18 
—mr shell program option, 2-3 
—mv shell program option, 2-3 


—n shell program option, 2-3 
name types, 3-4 

NDEBUG macro, 5-2 

NULL macro, 5-6 


—o code generator option, 2-13 

—0 linker option, 2-15 

object alignment, 3-6 

object format converter, 1-3 

object libraries, 2-15 

offsetof macro, 5-6 

operation of the compiler, 2-1—2-20 
overflow, 4-18 


—p preprocessor option, 2-7 
packing structures, 4-5 
parser (dspcc), 2-11 
invocation, 2-11 
options, 2-12 
—q, 2-12 
~Z, 2-12 
passing parameters to a function, 4-8 
PC installation, 1-4 
—pc shell program option, 2-3 
pointers, 3-5 
data size, 3-5 
~—pp shell program option, 2-3 
predefined names, 2-7 
preprocessor (dspcpp), 2-6, B-2 
invocation, 2-6 
options, 2-3, 2-6 
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—C, 2-6 
—d, 2-6 
—i, 2-7 
—p, 2-/ 
—q, 2-/ 
preprocessor directives, B-1 


program termination functions 
abort (exit), 5-16 
atexit, 5-23 
exit, 5-30 

ptrdiff_t type, 5-6 


—q code generator option, 2-14 
—q parser option, 2-12 

—q preprocessor option, 2-7 
—q shell program option, 2-3 
—qq shell program option, 2-3 


RAM model of autoinitialization, 2-15—2-20, 
4-3 

RAND_MAX macro, 5-7 

realloc function, 4-5 

register conventions, 4-6—4-22 
dedicated registers, 4-6 
register variables, 4-7 

register variables, 3-9, 4-7 

reserved registers, 4-6 

reset vector, 2-16 

ROM model of autoinitialization, 2-15—2-20, 
4-3 

rts.lib, 2-15—2-20, 5-1 

rts.src, 4-4, 5-1, 5-7 

runtime environment, 4-1—4-22 
floating-point expression analysis, 4-19 
function call conventions, 4-8—4-22 
integer expression analysis, 4-18 
interfacing C with assembly language, 

4-11 
assembly language modules, 4-11 
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defining variables in assembly lan- 
guage, 4-13 
inline assembly language, 4-14 
modifying compiler output, 4-15 
interrupt handling, 4-16 
memory model, 4-2—4-22 
allocating variables, 4-3 
dynamic memory allocation, 4-5 
field manipulation, 4-5 
RAM model, 4-3 
ROM model, 4-3 
sections, 4-2 
structure packing, 4-5 
register conventions, 4-6—4-22 
runtime stack, 4-4 
system initialization, 4-20—4-22 
runtime initialization, 2-15 
runtime stack, 4-20 
runtime support, 2-15 
runtime-support functions, 5-1—5-15 
descriptions, 5-14—5-15 
summary table, 5-8—5-15 


—s shell program option, 2-3 
sections, 4-2 
.bss, 4-2, 4-3, 4-4 
.cinit, 4-2, 4-3, 4-20, 4-21 
data, 4-3 
text, 4-3 
shell program, options 
—al, 2-3 
—ap, 2-3 
—as, 2-4 
—ax, 2-4 
—C, 2-3 
—dNAME, 2-3 
—i, 2-3 
—k, 2-3 
—ma, 2-3 
—mr, 2-3 
—mv, 2-3 
—n, 2-3 
—pc, 2-3 
—pp, 2-3 
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—uNAME, 2-3 

—Z,2-3 
simulator, 1-3 
size_t type, 5-6 
software development system, 1-3 
software installation, 1-4 
SP register, 4-4, 4-6, 4-8 
stack, 4-4 
stack management, 4-4 
stack pointer, 4-4, 4-6, 4-8 
STACK_SIZE constant, 4-4 
static variable, 3-9 
static variables, 4-3 

reserved space, 4-2 
stdarg.h header, 5-6, 5-10 
stddef.h header, 5-6 
stdlib.h header, 5-7, 5-11 
storage class specifiers, 3-6 
string functions, 5-7, 5-12 

memchr, 5-44 

memcmp, 5-45 

memepy, 5-46 

memmove, 5-47 

memset, 5-48 

strcat, 5-59 

strchr, 5-60 

strcmp, 5-61 

strcoll, 5-61 

strepy, 5-62 

strcspn, 5-63 

strerror, 5-64 

strlen, 5-65 

strncat, 5-66 

strncmp, 5-67 

strncpy, 5-68 

strpbrk, 5-69 

strrchr, 5-70 

strspn, 5-71 

strstr, 5-72 

strtok, 5-74 
string.h header, 5-7, 5-12 
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structure packing, 4-5 

Sun-3 installation, 1-6 

system constraints 
MEMORY_ SIZE, 4-5 
STACK_SIZE, 4-4 

system initialization, 4-20—4-22 
autoinitialization, 4-21 
runtime stack, 4-20 

system stack, 4-4 

_ _SYSTEM_SIZE, 5-7 





—t code generator option, 2-14 
.text section, 4-2 
type specifiers, 3-7 


—uNAME shell program option, 2-3 
#undef directive, B-2 

underflow, 4-18 

uninitialized sections, 4-2 


variable allocation, 4-3 
variable argument functions, 5-6 
variable argument functions and macros 
va_arg, 5-79 
va_end, 5-79 
va_ Start, 5-79 
variable argument macros, 5-10 
VAX installation, 1-5, 1-6 











XDS emulator, 1-3 


z code generator option, 2-14 
—Z parser option, 2-12 
~z shell program option, 2-3 
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